AdsAgent — TikTok Ads MCP

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

Annotations only give the safe/unsafe profile (destructive, openWorld); the description goes far beyond it with sequential-not-atomic execution, stop-on-failure, per-item receipts, spend impact, idempotent repeat behavior, retry_at resume semantics within expiry, and the caveat that a submitted background task is not a verified provider change.

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 and identity, then the constraints. It is long because the tool is high-risk, but several sentences drift into UI/approval-presentation policy ('Show account and target names, operation, before/after values...') that could be trimmed without losing invocation guidance.

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, and the description compensates with per-item receipt reporting, failure/uncertain states, and retry behavior. Given a destructive, open-world executor this is largely sufficient, though the return shape and connection_context usage remain unstated.

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

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

Schema description coverage is 0%, so the description must carry the load. It does add real meaning for expected_changes ('the exact expected_changes returned by prepare ... the server rejects any mismatch') and expected_plan_digest, but says nothing about approval_ref beyond naming it and never mentions connection_context.

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

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

States a concrete verb+resource (execute the stored mixed advertising plan) and pins identity to approval_ref and expected_plan_digest. It is clearly distinguishable from approval_plan_prepare, approval_plan_get and approval_plan_deny, which the sibling list shows are the near-miss alternatives.

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?

Specifies the precondition (explicit user approval of every displayed item), the required inputs from prepare, and the failure condition (server rejects mismatches). It also spells out when to resume versus re-review ('changed or expired plans require review').

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, readOnlyHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: it is a local-only discard ('No TikTok changes') that preserves completed item receipts, which the annotations cannot express. It does not cover idempotency or error behavior.

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

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

Two short sentences, zero filler. The scope and state precondition are front-loaded, and the effect disclaimer follows immediately.

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 lifecycle tool with no output schema, the description covers the important unknowns: which states are deniable, what survives (completed receipts), and that no external system is touched. It stops short of saying what the caller receives back or what happens to incomplete items.

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 0% across 3 parameters, so the description carries the full burden and documents none of them. approval_ref, expected_plan_digest, and the connection_context pattern are left entirely unexplained, including the digest's role as a concurrency/confirmation guard.

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 (discard) and resource (a prepared or quota-waiting mixed approval), and qualifies which lifecycle states are eligible. 'No TikTok changes' implicitly separates it from approval_plan_confirm, which is the sibling that does touch TikTok. The jargon 'mixed approval' is left undefined, keeping it from 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 'prepared or quota-waiting' gives a concrete precondition for when this tool applies, and 'No TikTok changes' contrasts with the confirm path without naming it. There is no explicit 'use X instead when...' routing, but the context is clear enough to select correctly.

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 reinforces this with 'no provider requests or state changes,' but adds nothing beyond annotations, such as error behavior when approval_ref is not found.

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 the read scope stated first and the negative constraint second. No wasted words.

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

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

For a simple read tool with no output schema, the description is minimally adequate but leaves the undocumented approval_ref identifier format and the meaning of 'item receipts' unexplained, which an agent would need to call and interpret the result 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 description coverage is 0% for two parameters. The description says nothing about approval_ref, its expected format, or what connection_context (an mctx_v1_ pattern token) is for. With zero coverage the description should compensate and does not.

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 stored mixed approval and its item receipts.' This distinguishes it from the mutation siblings approval_plan_prepare/confirm/deny, though the term 'mixed approval' is domain jargon that isn't explained.

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 'no provider requests or state changes' implicitly contrasts with the prepare/confirm/deny siblings, giving an implied usage context. However, no alternative tool is named and no explicit when-to-use condition is 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?

Adds substantial context beyond the annotations: 'sends no advertising changes', sources become immutable members, drafts 'cannot be confirmed separately', handles must stay out of normal chat, never replay an uncertain write, and waiting_quota plans retain their confirmation until original expiry. Those are exactly the behavioral traits an agent needs. Not a 5 because it doesn't clarify whether the approval later executed by approval_plan_confirm is bound to the exact captured state or how the expiry window is determined on creation.

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

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

It is front-loaded correctly, but then crams roughly eight distinct topics (display rules, privacy rules, confirmation behavior, reporting semantics, retry safety, expiry behavior, per-item source protocols) into one undifferentiated paragraph. Sentences like 'Report each completed, submitted, waiting, failed or uncertain item accurately' and 'Keep these handles private' add little and bloat the 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?

For a two-parameter tool with no output schema and no annotation coverage of its behavioral contract, it does cover the critical semantics around immutability, expiry, and idempotency. But it leaves the connection_context parameter undocumented and never states whether the returned approval is the same object later passed to approval_plan_confirm or how it should be referenced.

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 0%, so the description must carry the parameter burden. It does explain the three mutually exclusive source handle types (approval_ref, approval_token with approval_ref, confirm_token) and the 1–20 bound, which is genuinely useful. But it never mentions 'connection_context', its required format, or how it relates to the mctx_v1 pattern, leaving that parameter unexplained.

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 opens with a concrete verb and resource: 'Combine 1–20 owned, unexpired, unconfirmed advertising drafts into one immutable approval.' That is specific and hard to confuse with the sibling approval_plan_confirm or approval_plan_get. It stops short of explicitly naming those siblings as the alternatives, so it doesn't quite reach 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?

It says the tool produces one approval for the complete requested change set and that each item accepts one of three source handles, which implies when to use it. But it never explicitly states when to prefer this over campaigns_quick_create_confirm, copy_ad_quick_copy_confirm, or the per-domain prepare/confirm pairs, which is the real ambiguity in this sibling group.

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/non-destructive/non-openWorld, and the description adds a lot beyond them: data is cached, membership-based filtering excludes accounts TikTok refuses, cursors can be rejected/expired, and 'complete' describes pagination rather than upstream sync coverage or create permission. That last clarification is exactly the kind of trait annotations cannot express.

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

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

The description is long but front-loaded and nearly every sentence carries information about behavior, pagination, or constraints. Minor slack exists (the Meta-MCP mirroring aside and the explicit REQUIRED/EXAMPLE boilerplate), but nothing is truly redundant.

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 4-param read tool with no output schema, the description supplies the row shape (owner_bc_name), page semantics, and cursor lifecycle that an output schema would otherwise provide. The only omission is connection_context, which does not block correct invocation for the common 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 description coverage is 0%, so the description must carry the load, and it does for three of four params: limit (default 20, max 50), search (case-insensitive native id/name lookup), and cursor (sourced from previous response, stale cursors require a restart). The fourth parameter, connection_context, is never mentioned, leaving a gap that keeps this below 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?

The opening sentence states a specific verb+resource+scope: list cached TikTok ad accounts (advertisers) for the authenticated tenant. It distinguishes itself from siblings like assets_list_business_centers, assets_list_tt_accounts, and assets_list_apps, and even clarifies the addressee semantics ('advertisers'). An agent can pick this tool without opening the schema.

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

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

It gives real usage context: only advertisers the connected member can currently operate are listed, and that the result mirrors the Meta MCP equivalent. It also prescribes how to iterate (keep the same tool/filters/limit, follow next_cursor serially) and when to restart page one. It stops short of naming an explicit alternative sibling or stating when NOT to use it, so not a 5.

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

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

Despite annotations already flagging destructiveHint=true, the description explains the actual destructive mechanism ('A live refresh can replace cached app rows for the selected advertiser') and enumerates the refresh outcome set (refreshed, rate_limited, no_permission, no_connection, failed). It also surfaces auth constraints ('create-capable authorization', 'do not create on it') and rate-limit signaling beyond what the annotations provide.

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 with purpose and return shape first, then parameters, then refresh semantics. It is long for a list tool and the note that a live refresh can replace cached rows slightly restates the earlier refresh guidance, but nearly every sentence carries operational 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?

No output schema exists, so the description supplies the return contract itself: bounded page, linked_bcs rows derived from linked_advertiser_ids → advertiser.owner_bc_id, next_cursor/complete pagination semantics, and coverage.live_refresh statuses. Combined with the refresh/cursor rules, an agent has everything needed to call this correctly and safely.

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 schema description coverage at 0%, the description carries the full burden and does so: limit (default 20, maximum 50), cursor (from previous response), search (case-insensitive native id/name lookup), refresh (first page, advertiser_id required), and advertiser_id (exact cached advertiser link, not shared BC ownership). Only connection_context (an internal token) is left undocumented, which 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 ('List cached TikTok app assets (App Promotion advertised apps) for the authenticated tenant') and even names the sibling asset type it relates to ('advertiser_id from assets_list_ad_accounts'). An agent can distinguish it from the other assets_list_* tools 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?

Gives explicit when/when-not conditions: use advertiser_id from assets_list_ad_accounts for creation, pass refresh=true only on the first page with advertiser_id, follow next_cursor serially with same filters/limit, and restart from page one on a rejected/old cursor. It also steers the agent away from creating when coverage.live_refresh reports no_permission.

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 non-obvious context: the data is cached, rows are augmented with computed counts, cursors can be rejected/expire requiring restart, and 'complete' does not imply upstream sync coverage or creation permission. Only freshness/staleness of the cache is left unstated.

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 purpose before pagination mechanics, and each paragraph has a distinct job (what it lists, return shape, pagination, caveats). It is somewhat dense and longer than strictly necessary, but no sentence is filler.

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

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

No output schema exists, and the description compensates by describing the return shape (compact bounded page, next_cursor, complete flag) and pagination semantics. Zero required parameters is clear, and the only real gap is the undocumented connection_context parameter.

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 0%, so the description must carry parameter meaning, and it does: limit (default 20, max 50), cursor (from previous response, can be rejected/old), and search (case-insensitive native id/name lookup). It omits connection_context entirely, which is the one parameter left undocumented in both schema and description.

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 cached TikTok Business Centers') plus scope ('for the authenticated tenant, across every connection') and notes the enrichment fields (advertiser_count, pixel_count). Clear and specific, but it differentiates only implicitly from siblings like assets_list_ad_accounts or assets_list_pixels by resource name alone, with no explicit contrast.

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?

Strong operational guidance on pagination protocol (keep same tool/filters/limit, follow next_cursor serially until complete=true, restart page one on a rejected cursor) and a useful clarification that complete refers to pagination rather than sync coverage. However, it never states when to choose this tool over sibling asset-listing tools, so alternative selection 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?

With destructiveHint=true already set, the description explains the mechanism behind it ('a live refresh can replace cached CTA portfolio rows for the selected advertiser') and notes server-side verification that the portfolio belongs to the same advertiser. It clarifies that complete refers to pagination, not sync coverage or permission to create, which is valuable context beyond the annotations, though it omits permission/rate-limit detail.

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

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

Purpose and scope are front-loaded, followed by usage, pagination, and refresh semantics in a logical order. It is dense but nearly every sentence adds operational information; the pagination paragraph is slightly verbose but earns its length given the complexity.

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 6-parameter, paginated, refresh-capable tool with no output schema and no schema descriptions, the description covers usage, pagination, refresh behavior, and prerequisites well. It stops short of describing the returned row shape (id/name fields), which the agent must infer.

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 0%, so the description carries the full burden and does so: it documents cursor (from previous response), limit (default 20, max 50), search (case-insensitive native id/name lookup), refresh (forces live read), and advertiser_id (required, from assets_list_ad_accounts). Only the internal connection_context is undocumented, which is acceptable.

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 cached TikTok CTA portfolios') scoped to 'one exact advertiser,' and names the sibling that supplies its required input ('advertiser_id from assets_list_ad_accounts'). An agent can distinguish it from the other assets_list_* tools without opening a schema.

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

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

Explicitly tells when and how to use it: feed the returned id as ad_params.call_to_action_id for Smart+ website-conversion creation, never guess an id, refresh only when cache is empty or refresh=true, and keep filters/limit fixed while following next_cursor until complete=true. Names the prerequisite tool and the restart rule on a stale cursor.

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

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

Annotations declare destructive=true but not what is destroyed; the description fills that gap by stating a live refresh can replace cached identity rows, and it documents permission/auth outcomes (coverage.live_refresh values including no_permission), rate limiting, and the one-off live verification behavior. This is substantial context beyond the structured 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?

Purpose is front-loaded, but the body is a dense wall of domain jargon crammed into long parenthetical run-ons. The information earns its place, yet the presentation is hard to parse and would benefit from tighter scoping or structure.

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 6-parameter tool with no output schema, the description covers pagination completion semantics, row fields (linked_bcs, regular_local_media_eligible), the coverage.live_refresh status vocabulary, and refresh caveats. An agent has what it needs to page, filter, and refresh 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?

With 0% schema description coverage, the description carries the burden and largely does: it gives limit defaults/maximum, cursor semantics and restart-on-rejection, search as case-insensitive native id/name, refresh requiring first page + advertiser_id, and advertiser_id scoping. Only connection_context is left undocumented.

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 up front ('List cached TikTok posting identities for the authenticated tenant') and extends it with the refresh capability. It also distinguishes itself from the surrounding asset-list siblings by naming the 'Meta pages analog' and its role in the discovery-before-create flow.

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 about when to call it: 'call this from assets discovery before campaigns_quick_create when ad_params lacks identity_id / identity_type'. It also names the alternative source (assets_list_ad_accounts for advertiser_id) and the exclusion (shared BC ownership alone is not an advertiser link).

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, openWorldHint=false, but the description adds substantial behavior beyond them: results carry public metadata and exact music_id only (no temporary URLs, signatures, tokens, or raw provider payloads), the server revalidates the id on the exact create route before issuing an approval, and saved templates retain an explicit track that preparation re-verifies.

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?

Well front-loaded: the library/scope statement comes first, then result-content caveats, then required/optional parameters, then an example. It is dense and every sentence is informative, though the saved-template and local-carousel sentences sit slightly off the core path of discovery and cost a bit of length.

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

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

For a read-only search tool with no output schema, the description explains what results contain, what is deliberately omitted, the required/optional parameters with ranges, pagination behavior, and how the returned music_id is consumed downstream. Nothing an agent needs to call it correctly 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 0%, so the description carries the full burden and does so well: advertiser_id must come from assets_list_ad_accounts, search is 1-100 characters, limit ranges 1..50, and cursor is the opaque next_cursor from the previous page with serial pagination rules. An example call is included.

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: searches TikTok's live advertiser-available music library, scoped to Smart+ SINGLE_IMAGE or CAROUSEL_ADS creation. It even delineates a boundary against a sibling by noting local carousel members come from creatives_list via image_creative_ids, so an agent can distinguish it without opening other schemas.

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 select a row with create_eligible=true and the required image format, then pass its music_id as ad_params.music_info.music_id. It also gives when-not guidance ('never guess or assume cross-advertiser availability') and pagination discipline (keep the same advertiser_id/search/limit, paginate serially, never fan out).

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

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

Annotations declare readOnlyHint=false and destructiveHint=true, indicating a mutation-capable tool. The description adds that a live refresh can replace cached pixel rows, which is useful context. However, it doesn't explicitly flag the destructive/overwrite nature as strongly as it could, and coverage.live_refresh outcomes are described but not the full impact.

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

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

The description is dense but well-organized, front-loading the core purpose and then detailing pagination, refresh behavior, and the creation path. It's longer than minimal but each paragraph covers a distinct concern.

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 6 parameters, no output schema, and 0% schema coverage, the description does a good job covering pagination, refresh semantics, coverage.live_refresh outcomes, and the advertiser_id requirement. It's missing connection_context and doesn't fully explain what the returned row structure looks like beyond linked_bcs.

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 0%, so the description must compensate. It explains cursor (from previous response), limit (default 20, max 50), search (case-insensitive native id/name lookup), advertiser_id (from assets_list_ad_accounts, required for refresh), and refresh (first page, advertiser_id required). It doesn't explain connection_context, but overall adds substantial meaning beyond the bare schema.

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

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

The description clearly states the tool lists cached TikTok pixels for the authenticated tenant with owning BC lists attached, and explains the linked_bcs derivation. It distinguishes itself from siblings like assets_list_ad_accounts and assets_refresh_all by focusing on pixel listing with BC linkage.

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 explains when to use advertiser_id (for creation, to get exact cached advertiser links) and when to use refresh (first page, advertiser_id required). It also warns that shared BC ownership is not an advertiser link and that the prepare step verifies authorization. Alternatives aren't explicitly named, but the usage context is clear.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), and the description adds meaningful context: bounded page size, cursor invalidation behavior, the warning that complete refers to pagination rather than upstream sync coverage, and that it confers no permission to create. This is real behavioral disclosure 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?

Purpose is front-loaded, followed by pagination semantics, then REQUIRED and an example. Mostly efficient, though the 'complete describes pagination, not upstream sync coverage or permission to create' clause is slightly defensive and could be tightened.

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 partially describes returns (compact bounded page, next_cursor, complete flag) and covers defaults, limits, and pagination discipline. It is complete enough to call correctly, though the connection_context parameter and exact page shape are 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 coverage is 0%, so the description must carry the load, and it documents three of four parameters well: limit (default 20, max 50), cursor (from the previous response, restart on rejection), and search (case-insensitive native id/name lookup). The connection_context parameter remains unexplained, though its pattern regex is largely self-describing.

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 cached TikTok Shops') and scopes it precisely to the authenticated tenant's Business Centers, even naming the upstream endpoint that populates the cache. An agent can immediately distinguish this from siblings like assets_list_business_centers or assets_list_tt_accounts.

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 operational guidance: keep the same tool/filters/limit while following next_cursor serially until complete=true, and restart from page one on a rejected or stale cursor. It clarifies the meaning of 'complete' but does not explicitly name alternative tools (e.g. assets_refresh_all) or when to prefer a live refresh over the cache.

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 a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false), and the description adds real context beyond them: the data is cached rather than live, results come back as a 'compact bounded page', a rejected or old cursor forces restarting at page one, and complete means pagination finished rather than upstream sync coverage or permission to create. That last clarification actively prevents a plausible misreading of the return 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?

Front-loaded with the resource and the identity-vs-account distinction, then pagination mechanics, then requirements and an example. The pagination guidance is repeated in slightly different words ('follow next_cursor serially' vs 'a rejected or old cursor requires restarting page one'), which is defensible given the failure mode it guards against, but keeps it from being maximally tight.

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 does the work of describing the return shape: a compact bounded page with cursor and complete, plus what complete does and does not mean. Combined with the pagination loop instructions and the explicit 'REQUIRED: none', an agent has enough to invoke and iterate correctly; only connection_context is left unexplained.

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 0%, so the description carries the burden, and it does for three of four parameters: cursor origin (from the previous response), limit (default 20, maximum 50), and search (case-insensitive native id/name lookup). The fourth parameter, connection_context, is never mentioned, leaving one gap that the zero-coverage schema does not fill.

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 cached TikTok accounts') and immediately pins down the scope: data sourced from Business Center assets. It also explicitly disambiguates from the sibling concept of identities ('These tt_account_id values are not posting identity_id values'), so an agent can tell it apart from assets_list_identities without opening either 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 an explicit when-not and an alternative: for ad creation use assets_list_identities with the exact advertiser_id, then preserve identity_type and identity_authorized_bc_id. It also states the pagination protocol (same tool/filters/limit, follow next_cursor serially until complete=true) and the recovery path for a rejected or stale cursor.

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/openWorld/destructive, but the description adds substantial context: results are cached (not atomic), no refresh or provider write occurs, cache evidence does not prove ownership/permissions/create eligibility, shared BC membership is not an asset link, and missing matches are inconclusive. That is genuinely beyond what the annotations provide.

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

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

Purpose is front-loaded and every sentence carries operational weight, but the block is dense and packed with caveats that could be grouped more tightly. Still appropriately sized for a high-complexity, 9-parameter lookup.

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 nine parameters, the description supplies the return shape (bounded nodes/edges with per-connection evidence), pagination semantics, and a long list of interpretive caveats. The only real gap is the unexplained connection_context parameter.

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 0%, so the description must carry the load. It documents the selector semantics (which of bc_id/advertiser_id/app_id/pixel_id/identity_id/connection_id to use and what each reveals), the exactly-one rule, and limit=1..50 default 20 plus cursor. It does not explain connection_context (the mctx_v1_ token), leaving one parameter undocumented.

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: reading the authenticated tenant's cached TikTok asset topology. It explicitly differentiates itself from the Meta counterpart (assets_lookup_business_links with Meta IDs) and from local creative tooling (creatives_list, create prepare), so an agent can place it precisely among siblings.

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

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

Gives explicit selection rules: exactly one native ID selector, which selector family maps to which relationship type (BC/account/connection = forward; app/pixel/identity = exact advertiser links), plus hard exclusions ('use TikTok selectors, not Meta business_id/page_id'). It also names the alternative tool for the separate creative-upload case.

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 flag a destructive, non-read-only mutation, and the description adds real behavioral value on top: it is asynchronous, returns per-task receipts and 'truthful admission failures', and warns 'submitted does not mean refreshed'. It stops short of explaining what the destructive refresh actually replaces or whether repeated calls are 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?

Dense but front-loaded, opening with the verb/resource and closing with the required polling workflow; every sentence carries operational information. The 'Meta-wire-aligned alias of `tiktok_refresh_assets`' phrase is slightly cryptic internal jargon but still useful routing information, so waste is minimal.

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

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

For an async mutation tool with no output schema, the description covers what an agent needs: the async task model, the polling siblings, the returned receipts/failures, and the warning that submission is not completion. The main gap is the undocumented `connection_context` parameter.

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 one parameter (`connection_context`) with 0% schema description coverage, and the description never mentions it, so it fails to compensate for the coverage gap. The only hint is 'for the authenticated tenant', which loosely implies tenant scoping but gives no format or meaning for the connection_context pattern.

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 precise verb (refresh) plus a specific resource (TikTok asset snapshots) and enumerates the covered asset classes (pixels/audiences/identities/shops/TT accounts/apps/CTA portfolios) and scope (every active pull-enabled connection for the tenant). It also positions itself against siblings by naming the alias relationship to `tiktok_refresh_assets` and pointing to `tiktok_get_assets_status`, so an agent can distinguish it from the `assets_list_*` family 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 clear downstream context: poll the returned task_ref (or task_id) with `tasks_get_status`, and check per-task results plus `tiktok_get_assets_status` before preparing creation. It does not spell out an explicit when-not or explain when to prefer this over the aliased `tiktok_refresh_assets`, so the routing is implied rather than fully prescribed.

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 and openWorldHint=true, so the mutation/live-effect profile is known. The description adds genuinely new behavior: the approval_ref is single-use, dispatch happens exactly once, and uncertain outcomes must not be replayed. It omits failure semantics and any auth/rate constraints.

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, no filler, with the core action and the single-use constraint front-loaded and the fallback tool named at the end.

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

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

For a destructive, no-output-schema confirmation tool, the description covers the essential risky semantics (single-use, no replay, alternative on uncertainty). It could still say what the caller should expect on success or what the original route reference means.

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 0%, so the description must carry parameter meaning. It explains approval_ref as a consumable single-use token (useful), but says nothing about connection_context, which is left entirely unexplained.

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 ('consume... and dispatch') and a concrete resource ('the exact recorded TikTok ad-group change'), plus a scope qualifier ('once'). It is clearly distinguishable from bid_prepare, though it never names that sibling or the other *_confirm tools 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?

Provides a real when-not rule: do not replay on an uncertain result, and route to operations_get instead. It does not state the prerequisite (that bid_prepare must have produced the approval_ref) or contrast with budget_confirm/delivery_status_confirm, so context is clear but not fully bounded.

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, openWorldHint=false and destructiveHint=false; the description meaningfully adds that no TikTok mutation occurs, that the operation is bounded to the tenant's own entities, and that the returned approval_ref is single-use. That is real context beyond the annotations, though 'bounded' is never defined and no expiry/one-shot failure behavior is described.

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 core action and the returned artifact, with no padding. The phrasing 'common-wire alias' is jargon that costs more than it communicates, but overall the density is good.

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 8-parameter, 7-required prepare tool with no output schema, the description covers the return artifact and the non-mutating nature, which is the most important part. It is nevertheless incomplete: the meaning of run_id, rule_id_and_version, idempotency_key and entity_refs is absent from both description and schema, and validation-failure behavior is unstated.

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

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

Schema description coverage is only 13% (essentially just target_value's 'Advertiser-currency units'), so the description must carry the load for run_id, idempotency_key, rule_id_and_version, connection_context and entity_refs — and it explains none of them. It only restates the unit semantics already in the schema and the adset/ad_group alias already visible in the enum, leaving seven required-or-near-required parameters uninterpretable.

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 (validate), resource (bounded tenant-owned TikTok ad-group bid change), unit semantics (advertiser-currency), and outputs a named artifact (single-use approval_ref). It also pre-empts a likely confusion by noting that 'adset' is only the wire alias, which cleanly separates it from the confirm-side siblings.

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

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

The statement 'This tool does not mutate TikTok' implicitly positions it as the pre-step to a mutating confirm call, and the sibling list contains bid_confirm, so the prepare/confirm workflow is inferable. However, it never explicitly says when to use this versus bid_confirm, or whether an approval_ref must be consumed by a specific sibling before it expires.

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 flag this as destructive, non-read-only and open-world, so the safety bar is pre-set. The description adds genuinely useful behavior beyond that: the ref is single-use ('consume one'), the dispatch happens exactly once, uncertain results are never replayed, and recovery happens through operations_get on the authorization route.

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 the core action and followed by the failure-handling rule. Every clause carries weight, though 'on the original authorization route' is slightly cryptic phrasing.

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 mutation with no output schema, the description covers idempotency and recovery well but omits the prerequisite flow (budget_prepare), the meaning of connection_context, and any notion of what is returned on success.

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 0%, so the description must carry parameter meaning. It references approval_ref only obliquely ('one budget approval_ref') without format or source guidance, and never mentions connection_context at all, leaving one of the two parameters fully undocumented.

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 and resource: consuming an approval_ref and dispatching the recorded TikTok budget change. It clearly implies the confirm step of a prepare/confirm pair, but never names budget_prepare as the thing that produces the ref, so sibling differentiation is inferred rather than stated.

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 implies the tool is used to confirm a previously recorded change and gives a strong recovery path for transport-uncertain results (operations_get). However it never explicitly states the precondition (a change prepared via budget_prepare) or when to use this rather than budget_prepare/approval alternatives.

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 mark it non-read-only, non-destructive, closed-world. The description adds real context beyond them: it creates no TikTok mutation, it returns a single-use approval_ref, and the change is bounded/tenant-owned in advertiser-currency units. It does not, however, describe the idempotency or run_id lifecycle.

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 and no filler. The non-mutation disclaimer and the adset/ad_group alias note each carry distinct, necessary 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?

No output schema and a complex 7-required-param tool, so the description carries more burden. It covers the key behavioral contract (no TikTok mutation, single-use ref) but leaves the idempotency_key, run_id, and rule_id_and_version semantics unexplained, which an agent needs to call 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?

With only 13% schema coverage across 8 params, the description must compensate, and it only clarifies two things: target_value is in advertiser-currency units and entity_type's adset is an alias for TikTok ad_group. run_id, entity_refs, idempotency_key, rule_id_and_version, and connection_context 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 ("Validate ... a budget change") plus scope (bounded, tenant-owned, TikTok campaign or ad-group) and the output (single-use approval_ref). It clearly reads as the prepare-phase counterpart to budget_confirm, though it never names that sibling 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 description implies the prepare-then-confirm flow via the approval_ref return and "does not mutate TikTok," but it never states when to call this versus budget_confirm, bid_prepare, or approval_plan_prepare, nor any prerequisites. Usage is implied rather than spelled out.

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?

Far beyond what readOnlyHint=false/destructiveHint=false convey, it discloses the two-phase prepare/confirm contract, confirm-token expiry (10 minutes), server-side re-validation before mutation, status defaults (DISABLE), image upload retry behavior (retry_after_seconds 10s reuse), and that local creatives are only synced to the advertiser after explicit confirmation. These are material operational traits an agent cannot infer from 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?

Content is mostly on-topic and front-loaded with purpose, confirm requirement, and required inputs, but the body is an extremely dense wall of ALL-CAPS sections with long run-on paragraphs and repeated restatements (e.g., create_eligible and identity handling recur). The size is defensible for a 58-param, three-mode tool, but the structure makes it hard to parse and several sentences could be trimmed.

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 tool of this complexity with no output schema, the description explains return values (confirm_token, human-readable summary, recipe, launch_readiness, needs_input with rejected_paths and next_action) and covers each mode's input contract. Nothing essential to calling it correctly 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 description coverage is 0% across 58 parameters, so the description carries the full burden and does so impressively: it explains creative source shapes, template selector semantics, Meta aliases (execution.budget.*, budget_level, title/headline→display_name), budget/schedule contracts, and append-mode target IDs. It does not cover every one of the 58 fields (e.g., spending_power, tracking_info, many targeting fields remain unexplained), so it falls short of full compensation.

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 opens with a precise verb+resource+mode statement ('Prepare one TikTok create operation in new, append-campaign, or append-adgroup mode') and immediately distinguishes itself from the sibling campaigns_quick_create_confirm by stating it does not publish until confirm is called. An agent can tell exactly what this tool is and how it differs from the confirm/deny siblings 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?

It gives explicit when-to-use conditions (three append modes with which fields to omit), prerequisites per mode (template required for new/append-campaign; 'without a selector, preparation returns needs_input/template_required'), and routes the caller to helper siblings (assets_list_ad_accounts, creatives_list, templates_get, assets_list_apps, spark_ads_list_posts). It also states what not to do ('never supply both target IDs', 'do not rewrite IOS14_CAMPAIGN').

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 readOnly=false, destructive=false, openWorld=false. The description adds far more: server validates all items on one advertiser/authorization route, executes serially after confirmation, journals one receipt per entity, stops on uncertain outcomes, never publishes by itself, and caps at 20 ads per approval. That is exactly the 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?

Front-loaded with the core action and constraints, but it is dense and long: Spark identity normalization, legacy split shape, receipt verification, CAROUSEL_ADS objective compatibility, and Smart+ exclusion are all packed in without paragraph breaks. Much earns its place, but several sentences (legacy shape, TT_USER/BC_AUTH_TT caveat) could be tightened or moved to a reference.

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

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

For a 15-parameter, nested, no-output-schema creation tool, this is close to complete: it covers required selectors, the two-step confirm protocol, Spark vs local creative identity handling, and constraints (2-20 ads, no Smart+, no auto-rewrite of objective). Gaps remain around the campaign_params/adgroup_params objects and connection_context, but an agent could call it correctly from this description.

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 0%, so the description must compensate, and it does for the key parameters: template_id/exact template_name selector, batch_items (one creative source per item, ad_name fallback from Spark listing), item-level ad_params overrides (AUTH_CODE identity, verified Spark identity fields), append_mode values plus required target and preview receipt, and the call_to_action/call_to_action_id requirement. It does not explain advertiser_id, connection_context, or the campaign/adgroup/params object fields, so not fully compensating.

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: prepare a bounded manual TikTok hierarchy of 2..20 ads under one campaign/ad group, preserving batch_items order. It clearly distinguishes itself from campaigns_quick_create (Smart+ / single-ad path) and campaigns_quick_create_confirm (the confirmation step), so an agent can tell it apart from siblings.

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

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

Explicitly routes the agent: Smart+ templates must go to campaigns_quick_create with one ad_params.creative_list; confirm only after explicit approval and only once; never fan out single-create calls; prepare another explicit batch beyond 20 ads. When-to-use, when-not-to-use, and alternatives are all named.

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

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

Despite annotations already flagging destructive/openWorld mutation, the description adds substantial context: async task execution, idempotent token recovery within expiry, that an unavailable token does not prove absence of a task, the shape of a failed terminal response (created objects, failure phase/reason/support_ref, next action), and a legacy recovery path. This far exceeds the annotation baseline.

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?

Content is largely non-redundant and front-loaded with the core confirm action, but it is delivered as a single dense paragraph mixing core semantics with niche edge cases (historical mislabeled UUIDs, legacy tenant-scoped paths). Readability suffers from the lack of structure despite little outright waste.

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 complex, non-read-only, no-output-schema tool, the description covers invocation prerequisites, idempotency/recovery semantics, async follow-up via tasks_get_status, and failure-response shape. An agent has enough to call it correctly and to handle lost or failed responses.

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 schema coverage at 0%, the description carries the burden and does well for confirm_token: it must come from a prior campaigns_quick_create call and is bound to its original expiry. It also disambiguates task_id from task_ref as inputs. However, the optional connection_context parameter is never explained, leaving one of two params undocumented.

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 ('Confirm') plus the exact resource ('the durable create approval minted by campaigns_quick_create'), immediately distinguishing it from the sibling that mints the approval. An agent can tell it apart from campaigns_quick_create, campaigns_recreate_confirm, and approval_plan_confirm 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?

Explicitly covers when to use (recovering a lost response with the same exact token) and when-not ('do not prepare a replacement'), plus named alternatives for uncertain outcomes (operations_get with operation_ref) and progress watching (tasks_get_status). It even forbids specific wrong approaches ('never replay or name-match').

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 and readOnlyHint=false, so the safety profile is covered. The description adds genuinely useful context beyond them: it clarifies that an already-claimed draft should be preserved, that submitted tasks are never cancelled, and that an expired/missing token does not prove no submission occurred.

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 caveats are front-loaded in the first sentence, and the REQUIRED/EXAMPLE block aids invocation. Slightly padded by restating a schema-level requirement, but overall tight and well-ordered.

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, no-output-schema tool the description handles the behavioral nuances well and does not need to explain return values. However, it leaves the connection_context parameter undocumented, so it is not fully complete for invocation.

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

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

Schema coverage is 0% for both parameters. The description restates that confirm_token is required (already in the schema) and gives a sample value, but the second parameter, connection_context, is entirely undocumented in both schema and description, leaving a real gap.

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

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

The description states a specific verb (deny) and resource (an unclaimed campaign draft minted by campaigns_quick_create), scoping it to the 'unclaimed' case and distinguishing it from the confirm flow. It is clear enough to tell apart from the sibling confirm tool, though it never names that sibling 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?

It gives a clear when-to-use ('deny an unclaimed draft') and an implicit when-not ('if already claimed, preserve the original receipt and follow its recovery action'), plus a boundary condition ('this never cancels a submitted task'). It stops short of explicitly naming the alternative tool to use instead.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the description doesn't need to restate the safety profile. It adds genuinely useful behavioral context the annotations cannot convey: idempotency semantics ("One durable task; a lost response may be recovered with the same unexpired token") and an explicit anti-replay warning, which directly addresses the risk of duplicate execution.

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 with the purpose front-loaded and no filler. Each sentence carries distinct information: action, recovery behavior, and replay prohibition.

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 mutation with no output schema, the description covers the approval prerequisite and idempotency but omits what a successful confirmation returns, the meaning of connection_context, and how the token is obtained. Annotations carry the safety profile, so the gap is moderate rather than severe.

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 0% for both parameters, so the description must carry the burden. It references an "unexpired token" that maps loosely to confirm_token, but gives no format, lifetime, or sourcing detail, and the connection_context parameter is entirely undocumented in both schema and description.

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

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

The description names a specific verb and resource ("Confirm one prepared TikTok task recreation") and scopes it to the confirm step, which distinguishes it from the sibling deny and prepare tools. It stops short of naming campaigns_recreate_from_task or campaigns_recreate_deny as its counterparts, so differentiation relies on the reader's inference.

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

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

It gives a precondition ("after explicit approval") and a caution ("Never replay a prior task directly"), which implies the when-to-use context. However, it never names the sibling alternative that prepares the task or the deny counterpart, leaving the routing decision implicit.

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 and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: only unclaimed plans are discarded, claimed plans retain recovery references, and already-submitted tasks are unaffected — all non-obvious consequences of the call.

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, with the core action stated first and the caveats after. Every clause carries information that the schema and annotations do not.

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 mutation with no output schema, the description explains the outcome well but omits the required token's origin and any error/eligibility conditions. It is adequate but leaves an agent guessing on the one required parameter.

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 0% and the description says nothing about either parameter. The required confirm_token in particular has no explanation of its provenance (presumably a prepare/recreate step) or lifetime, so an agent gets no help from the text on how to supply 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 and resource ('Deny an unclaimed TikTok recreation') with a scope qualifier that the title alone does not carry. An agent can pair it with the sibling campaigns_recreate_confirm by the deny/confirm naming, though the description never names that 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?

The word 'unclaimed' implies a precondition and 'this does not cancel submitted tasks' draws a boundary, but the description never states when to choose this over campaigns_recreate_confirm or what makes a recreation 'unclaimed'. Usage is inferable rather than spelled out.

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 destructiveHint=false; the description adds substantial traits beyond that: payload is loaded server-side, internal receipt/route fields are stripped, ownership and parent bindings are revalidated at prepare time, and source end times are never auto-extended. This tells the agent this is a non-executing preparation step whose behavior is bounded and non-destructive.

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?

Five tight sentences, front-loaded with what the tool does and then layering eligibility, scheduling, and constraints. Every sentence adds an actionable fact and none restates the title or the schema.

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

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

With no output schema and only three annotation hints, the description carries the burden well: purpose, server-side processing, eligibility, and parameter usage are all covered. The remaining gap is lifecycle guidance — what state is produced, whether it expires, and the required call to campaigns_recreate_confirm/deny.

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 0% at the top level, so the description must compensate. It explains that task_ref is an opaque handle and that execution.start_time/end_time drive an explicit reschedule, but connection_context (mctx_v1 pattern) is never mentioned, leaving one of three parameters undocumented in both schema and description.

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 ('Prepare a recreation of ... a TikTok create/copy task') and scopes it to caller-owned, fully completed tasks identified by task_ref. It is clear what the tool does, but it never names its natural siblings campaigns_recreate_confirm / campaigns_recreate_deny, so the two-phase prepare/confirm pattern must be inferred.

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 real eligibility context: only fully completed, caller-owned tasks are recreatable, and failed/partial/uncertain/foreign tasks are explicitly excluded. It also tells the caller to use execution.start_time/end_time for a rescheduled launch, but it omits the follow-up step (confirm/deny), so no alternative is named.

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

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

Annotations already declare non-read-only, non-open-world, non-destructive behavior, and the description adds substantial operational context beyond them. It discloses same-advertiser-only transfer, one approval and one serialized task journal, media reuse limitations, and precise execution-time replacement semantics. Nothing here contradicts 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?

The description is a dense block, but it is front-loaded with the core purpose and then layers usage, constraints, and scheduling behavior. Nearly every sentence adds distinct operational value. It could be slightly more scannable, but it is appropriately sized for a complex clone-preparation 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?

For a complex prepare tool with confirm/deny siblings and no output schema, the description covers the essential workflow, constraints, and alternatives. It mentions approval and task journal behavior, which implies the confirmation flow, though it does not name the confirm/deny siblings explicitly. Overall it is nearly complete for correct invocation.

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

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

With 0% schema description coverage, the description must carry parameter meaning and does so well for the critical parameters: exactly one of source_campaign_id or source_adgroup_id, copies 1..5, and start/end time replacement rules. It does not explain advertiser_id or connection_context, leaving some gaps, but it compensates for most of the important inputs.

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

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

The description states a specific verb and resource: preparing a same-advertiser TikTok campaign or ad-group structural clone from live TikTok structure. It explicitly distinguishes this tool from the new-launch path using creatives_list and campaigns_quick_create, so an agent can tell it apart from siblings. Scope is narrowed with 'same-advertiser' and 'from live TikTok structure'.

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 explicit when-to-use guidance: only when the user explicitly asks to clone an existing campaign or ad group. It also provides the alternative workflow for new launches and says 'not this tool,' which is direct routing. Additional constraints like providing exactly one source ID and copies 1..5 further constrain usage.

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=true, so safety is covered. The description adds real value beyond that: durability ('one durable task'), polling via task_ref, recovery via operation_ref, and idempotent token reuse for a lost response. It does not, however, explain what the confirm actually mutates or the destructive consequence.

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 with the purpose front-loaded, followed by task/recovery semantics. Every sentence carries content; slightly dense but 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 no-output-schema confirm tool, the description usefully explains the returned task_ref/operation_ref and recovery path. It is somewhat incomplete on the connection_context parameter and on the concrete effect of confirming, but covers the operational essentials.

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 0%, so the description must compensate. It adds meaning to confirm_token ('the same unexpired token', recoverable, single-use) but says nothing about connection_context, leaving one of the two parameters fully undocumented in both schema and description.

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

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

The description states a specific verb (confirm) and resource (one prepared TikTok structural clone), and the word 'prepared' implicitly separates it from the prepare-side sibling copy_ad_clone_structure. It does not name that sibling or the deny sibling explicitly, so sibling differentiation is inferential rather than stated.

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 usage precondition ('after explicit user approval') and implies a prior preparation step ('one prepared ... clone'), which is useful context. However, it never names the prepare/deny alternatives or states when NOT to use this tool, leaving 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 destructiveHint=true, and the description adds real behavioral nuance beyond them: claimed plans retain recovery references and submitted tasks are not cancelled. This clarifies the blast radius of the operation, though it does not address auth requirements or confirm_token semantics.

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 terse sentences, with the core action front-loaded and the caveat about retained references following. No filler, though the second sentence is somewhat dense and could be clearer.

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 deny action with no output schema, the behavioral caveats are useful, but the complete absence of parameter documentation (especially the required confirm_token) leaves a notable gap an agent must fill from inference alone.

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 0% and the description says nothing about either parameter. The required confirm_token and the mctx connection_context pattern are documented nowhere, so an agent gets no guidance on what values to supply.

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

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

The description states a specific verb and resource: 'Deny an unclaimed TikTok structural clone.' Combined with the title ('Discard a TikTok structure clone draft') it is clear this terminates a pending clone. It does not explicitly name the sibling confirm tool, but the prepare/confirm/deny pattern makes the purpose inferable.

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 qualifier 'unclaimed' implies the condition under which denial applies, and the sibling set (copy_ad_clone_structure_confirm) makes the alternative obvious. However, the description never explicitly states when to choose deny over confirm or what prerequisites exist, leaving usage 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 only declare readOnly=false, destructive=false, openWorld=false; the description adds real behavioral context beyond that: the server reads source settings once, preserves Smart+/Spark identity semantics, keeps the new ads disabled, binds a single aggregate approval, and enforces same-advertiser scope. That materially changes how an agent plans the call.

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

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

It is front-loaded with the core purpose and every sentence carries substantive information, with no filler. The single dense paragraph makes the mode-specific rules harder to scan than a short structured list would, but 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?

For an 11-parameter mutation-style tool with no output schema, the description covers modes, constraints, side effects, and scheduling overrides well. It omits what the call returns (the handle feeding copy_ad_quick_copy_confirm/deny, despite referencing an "aggregate approval") and leaves connection_context undefined.

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 0% schema description coverage across 11 parameters, the description carries the full burden and mostly succeeds: it constrains copies to 1..10, source_ad_ids to 1..20, names copy_mode=reuse|fresh, ties creative to fresh mode, and documents execution.start_time/end_time as ISO8601. Gaps remain: append_mode's accepted values and connection_context are never explained.

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

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

The description names a specific verb and resource ("Prepare a TikTok-native copy without publishing") and enumerates the two operating modes, so the agent knows exactly what the tool produces. It does not, however, differentiate itself from the close sibling copy_ad_clone_structure, which an agent could easily confuse with this one.

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 explicit invocation conditions per mode: single-source needs advertiser_id + source_ad_id with copies 1..10, grouped append needs source_ad_ids (1..20) plus a campaign or adgroup target, and "Grouped copy supports reuse only." It also supplies negative guidance ("never use Meta append-adset or client-side fan-out"), but it never routes the agent between this tool and copy_ad_clone_structure.

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 (destructiveHint=true, openWorldHint=true), yet the description adds real behavioral context beyond them: it returns operation_ref and task_ref, is single-shot ('confirm once'), and specifies idempotent recovery semantics for a lost response (reuse the exact token within its original expiry). This is genuinely useful operational disclosure.

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 and return refs, followed by tightly packed operational rules. Every clause is functional, though the recovery/idempotency sentences are dense. Effectively sized for a stateful confirm 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?

No output schema exists, and the description explicitly names the returned refs (operation_ref, task_ref), the polling path, and the failure/recovery path. For a mutating confirm step, this covers the agent's decision loop end to end.

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 0%, so the description must carry both parameters. It conveys the token's semantics (exact, expiry-bound, single-use for recovery) but says nothing about the second parameter, connection_context, nor the token's format. Partial compensation for a two-parameter tool with zero schema documentation.

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 (Confirm) and resource (prepared copy/bulk-append plan) with scope ('exactly one... after explicit user approval'). The word 'prepared' cleanly distinguishes it from the copy_ad_quick_copy prepare sibling and copy_ad_quick_copy_deny. An agent can identify this as the commit step 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?

Gives explicit when-to-use ('after explicit user approval', 'confirm once'), names the follow-up alternative (poll tasks_get_status), and names the fallback for uncertainty (operations_get on the original route). It also states what NOT to do: never replay, never recover by name, never prepare a replacement copy.

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, readOnlyHint=false, openWorldHint=false, and the description goes beyond them by describing state-dependent behavior: claimed plans return original recovery references, and submitted tasks are unaffected. That scoping of blast radius is genuinely useful, though the 'recovery references' return semantics remain vague.

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 scoped with the unclaimed/claimed distinction and the task-cancellation caveat. No filler, though the second sentence is densely packed and slightly ambiguous in phrasing.

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, non-idempotent action with no output schema, the description covers the safety-adjacent behavior reasonably but omits any parameter guidance and does not say what the tool returns on success or how it differs from approval_plan_deny / campaigns_quick_create_deny in the sibling set.

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?

Two parameters with 0% schema description coverage, and the description says nothing about either. The required confirm_token and the regex-constrained connection_context are left entirely unexplained, so an agent gets no help on supplying them correctly.

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: 'Deny an unclaimed TikTok copy plan,' which lets an agent distinguish this from the sibling copy_ad_quick_copy_confirm without opening either schema. The mismatch between the name's 'copy_ad_quick_copy' and the title/description's 'copy draft/plan' wording is minor but slightly blurs the resource identity.

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 agent can infer this is the rejection counterpart to a quick-copy confirmation. It adds one useful exclusion ('this does not cancel submitted tasks') but never names the alternative tool or states the prerequisite for when denying is appropriate.

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 and readOnlyHint=false, and the description is fully consistent with them while adding context they cannot: the two outcome branches (bytes verified -> creative ready; otherwise placeholder discarded), the idempotency contract, the safety guarantee that a verified ready creative is never deleted, and an explicit non-disclosure guarantee for hash, storage key, provider URL, and tenant id.

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, each load-bearing: purpose first, then the required matching parameters, then the outcome and safety guarantees. No restatement of the title and no filler, despite the density of information conveyed.

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 mutation tool with no output schema, it covers what the call does, what it needs, what results, and what is deliberately not returned. The only true gap is error/permission behavior (e.g. what happens if the idempotency_key or parameters do not match the original request), which the description does not address.

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 0%, so the description carries the burden. It annotates four of five parameters with real semantics (file_hash as SHA-256, a stable idempotency_key, the matching upload_attempt and folder_id) and ties them to the originating request_upload_v2 call. Only connection_context is unexplained, and its pattern makes it self-evidently plumbing.

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+scope: reconcile or discard one exact tenant-owned pending/error upload. It clearly distinguishes itself from creatives_delete and creatives_reconcile by describing the placeholder lifecycle it targets, so an agent can route between siblings without opening schemas.

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 triggering situation ('a failed browser upload does not remain as a permanent library placeholder') and the key prerequisite ('pass the same SHA-256 file_hash, stable idempotency_key, upload_attempt, and folder_id used for creatives_request_upload_v2'). It also implicitly rules out the delete tool by stating it never deletes a verified ready creative, though no sibling is named as the alternative for that case.

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 read-only, non-destructive, non-open-world profile. The description adds genuinely new behavioral context beyond them: the binding precondition and the explicit statement that agents cannot perform binding, which prevents a fruitless attempt loop. It does not disclose what 'status' values can be 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?

Two sentences, zero filler, and the more decision-relevant constraint (agents cannot bind) is placed up front. Nothing to trim.

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 some burden for return values, and it does not say what statuses are reported or what the agent should do with each. Combined with the undocumented connection_context parameter, a small but real gap remains for a tool meant to gate a human-driven 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?

There is one parameter, connection_context, with 0% schema description coverage and a non-obvious required pattern (mctx_v1_ + 64 hex chars). The description says nothing about what this parameter is, where the agent obtains it, or whether it is optional — leaving the only parameter 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: 'Read-only Google Drive library status for the current user.' This is distinguishable from sibling creatives_list_cloud / creatives_list, which deal with creatives rather than Drive binding state. It does not explicitly name a sibling to contrast with, so a 4 rather than 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?

Clearly frames the operational boundary: binding must be done by a human in the browser and agents cannot bind, which tells the agent this tool is for checking state, not changing it. It stops short of naming alternatives (e.g. which tool to call after binding succeeds) or stating when the status is meaningful (pre/post binding).

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

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

Annotations declare readOnly=false, openWorld=false, destructive=true, so the safety profile is covered structurally. The description adds real behavioral context: the exact success condition (size + content type match, plus checksum when available), the effect (marks row create-eligible), and a non-retry caution implying non-idempotence.

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 purpose, then usage conditions, then behavioral caveats, then a params block. Sentences earn their place, though the REQUIRED/EXAMPLE block partly restates what the input schema already marks as required.

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, and the description compensates by describing the successful response payload (an additive upload_contract projected from the persisted ready/reconciled row). Coverage is solid, with only connection_context left unspecified.

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 0%, so the description must compensate. It usefully documents creative_id's origin and format (UUID from request_upload or creatives_list), but leaves the optional connection_context parameter completely unexplained in both schema and description.

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+scope: 'Verify or safely reconcile a tenant-owned creative in R2.' It names the sibling tools it relates to (request_upload, creatives_list), letting an agent distinguish it from creatives_reconcile without opening schemas.

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 both trigger conditions ('after a newly prepared upload' and 'when creatives_list reports readiness.status=verification_pending') and adds a when-not ('Never auto-retry a failed confirmation'). Nothing 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=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real value beyond them: the name-uniqueness constraint within a parent and the subtle updated_at semantics on the returned row. It still omits failure behavior (e.g., what error a duplicate name produces) and whether folders are auto-named or reordered.

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 purpose, then a constraint, then a labeled REQUIREED/Optional/EXAMPLE block that is easy to scan. The updated_at note is tangential to creating a folder and slightly interrupts the flow, but it earns its place by preventing a misread of the returned row.

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

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

There is no output schema, so it is helpful that the description comments on the returned row's updated_at meaning. For a three-parameter creation tool with annotations covering safety, the only real gap is duplicate-name failure behavior and the undocumented connection_context parameter.

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 0% schema description coverage the description must carry the load, and it does for two of three parameters: name is marked REQUIRED (str), parent_id is explained as the parent folder UUID with 'omit for top-level' semantics. The connection_context parameter is never mentioned, and the single example only exercises the required field with no parent_id case.

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

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

The description states a specific verb and resource (create a creative folder) plus the tenant scope, so an agent immediately knows what operation runs. It does not explicitly distinguish itself from nearby siblings like creatives_rename_folder or creatives_delete_folder, relying on the verb alone to do that work.

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 agent learns the folder is tenant-scoped and that parent_id should be omitted for top-level folders, which is genuine routing guidance for the parameter. There is no explicit when-not-to-use or named alternative, and nothing about what to do when a name collision occurs.

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 and readOnlyHint=false. The description adds genuinely useful behavioral detail beyond annotations: it removes the DB row and conditionally deletes the R2 object only if no other rows reference it. That conditional cascade logic is not derivable from annotations or schema. It stops short of stating irreversibility or permission requirements, hence not a 5.

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

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

Front-loaded with the core action, then the cascade behavior, then the required-param note and a concrete example. Zero filler; 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 destructive single-object delete with no output schema, the description covers what it removes and the conditional R2 cleanup, which is the most important context. However it omits irreversibility, permission/tenant-auth requirements, and leaves connection_context undescribed, leaving gaps for a destructive 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 description coverage is 0%, so the description must compensate. It documents creative_id as a UUID string and marks it REQUIRED, which is helpful, but the second parameter (connection_context, with a strict pattern) is entirely undocumented in both schema and description. Partial compensation only.

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 (delete) and resource (a single creative) scoped to the authenticated tenant by creative_id. It is clearly distinguishable from siblings like creatives_delete_folder or creatives_abandon_upload.

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 verb 'delete' and the required creative_id, but there is no explicit guidance on when to use this vs alternatives (e.g., creatives_abandon_upload for in-progress uploads, or creatives_delete_folder for folders). No exclusions 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 destructiveHint=true, so the safety profile is known; the description adds real value by spelling out the cascade (subfolders, contained creatives) and the conditional R2 blob deletion rule when no other creative row references the key. It does not, however, mention irreversibility/recovery, permission requirements, or rate limits.

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 cascade behavior is front-loaded and the required-parameter note follows efficiently. The inline EXAMPLE is somewhat redundant with the schema's required list but is short and useful for call formatting.

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, no-output-schema tool, the description covers the key risk (recursive, irreversible-by-implication cascade and orphan cleanup). It stops short of stating permissions, rollback/confirmation behavior, or what happens on partial failure, which would matter for an agent invoking a destructive operation.

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 0%, so the description must compensate. It documents folder_id (required, string, UUID format) with an example call, which is genuinely helpful, but leaves connection_context entirely undocumented in both schema and description.

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 (Delete), resource (creative folder), and the exact scope (recursively, including subfolders and contained creatives). Combined with the name, an agent can immediately distinguish it from the sibling creatives_delete (which removes a creative, not a folder) and creatives_rename_folder.

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 never says when to choose this tool over alternatives like creatives_delete, usages_list_folders, or rename_folder, nor does it state prerequisites such as folder ownership or that a confirmation step precedes it. Usage is only implied by the name and the recursive scope.

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 readOnly/non-destructive/closed-world, and the description goes well beyond them: it discloses the returned fields (artifact_ref, download_endpoint, download_url when storage-verified), the deliberately withheld data ('provider URLs and storage identifiers are never returned'), and the non-raising 404 shape ('{status: "not_found"}'). These are concrete behavioral traits not present in any structured field.

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

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

Purpose is front-loaded and the REQUIRED/EXAMPLE lines add useful structure. The middle sentence is dense with jargon ('credential-free ArtifactDescriptor projection') but it does communicate the artifact_contract return, so little 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?

No output schema exists, so the description carries the return-value burden and does so thoroughly (artifact_ref, download_endpoint, artifact_contract, 404 shape, withheld data). The only meaningful gap is the undocumented connection_context parameter and the absence of any auth/permission notes.

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 0% schema description coverage the description must carry the param burden. It adds real value for creative_id by specifying the UUID format ('REQUIRED: creative_id (str — UUID)'), but the optional connection_context parameter and its mctx_v1_ pattern are left entirely undocumented, so only half the parameters are compensated for.

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

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

States a specific verb and resource ('Get a single creative ... by creative_id') and scopes it to resources 'owned by the authenticated tenant'. This cleanly distinguishes it from the list-style sibling creatives_list and the folder/deletion siblings, so an agent can select it 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?

The description conveys what a fetch does but gives no explicit guidance on when to use this over creatives_list, creatives_list_cloud, or creatives_list_folders, and no prerequisites or exclusions. Usage is only weakly implied by 'by creative_id'.

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 a safe read (readOnlyHint=true, destructiveHint=false), but the description adds substantial behavior beyond them: cursor is opaque and scope-bound, pagination must continue serially, rows omit content hashes/storage keys, legacy download_url only works after storage verification, and unverified rows report verification_pending. It also documents the coverage/readiness fields that gate downstream use.

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 scope constraints are front-loaded, and most sentences carry real operational content (empty_reason taxonomy, creative_id aliasing, coverage fields). However, the definition is a dense wall of run-on sentences mixing pagination, folder semantics, carousel rules and empty-state taxonomy, making it harder to scan than it needs to be.

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 explain returns and does: count, complete, meta.has_more, next_cursor, snapshot_at, the legacy top-level has_more, per-row creative_id as an alias of id, and the coverage fields. Combined with the empty_reason and readiness guidance, an agent has everything needed to call 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 description coverage is 0% and there are no enums in the schema, so the description carries the full burden and does so: scope (library|root with semantics), folder_id, cursor (opaque, scope-bound, reusable only with the identical query), limit (1..50, default 20), search (filename substring, max 200 chars), media_type and time_filter value sets, and include_incomplete. Only connection_context is left undocumented, which is minor.

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 opening sentence gives a specific verb and resource with scope: 'List creatives owned by the authenticated tenant with cursor pagination.' It then explicitly disambiguates the resource from siblings/adjacent systems ('the TikTok AdsAgent tenant library ... not Meta adsagent.md and not TikTok Ads Manager Material Center'), letting an agent separate it from creatives_list_cloud, creatives_list_folders and creatives_get.

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 is unusually explicit about when to use which scope ('library ... entire tenant library ... use root for root-only reads'), when to retry ('no_creatives_in_root ... retry scope=library (default) or call creatives_list_folders'), and where the output is consumed ('before using creative_id in campaigns_quick_create'). It also states the only true empty-library signal, so the agent knows how to distinguish a real empty result from a filter miss.

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 readOnlyHint/destructiveHint annotations, the description discloses the important behavioral trait that this reads from a local broker index and never calls Drive, implying possibly-stale cached data. It also tells the agent what the rows carry (selection_key in gdrive: form), which the annotations do not.

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 source constraint ('never calls Drive') and the downstream-use hint are both front-loaded and each 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?

With no output schema and no documented parameters, the description covers the read-only nature and row payload adequately but leaves the input contract (especially q and connection_context) entirely unexplained, which is a real gap for a listing 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?

Three parameters (q, limit, connection_context) have 0% schema description coverage, and the description explains none of them - not the query semantics of q, nor the meaning/default behavior of limit, nor the connection_context pattern. The description does not compensate for the schema gap.

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 (Google Drive files/creatives) plus the exact data source (the local broker index), which meaningfully separates it from the broader creatives_list sibling. It stops short of naming that sibling explicitly, so an agent must infer the distinction.

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

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

Usage is implied rather than stated: it hints that returned selection_key values feed 'create flows', which suggests when the results are useful. There is no explicit when-to-use or when-not-to-use guidance versus creatives_list, creatives_get, or creatives_list_folders.

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 adds real behavioral value: each folder carries creative_count, empty results relate to coverage.empty_reason, and a NOTE warns that updated_at is 'row last touched' not 'content changed', advising self-diffing. This is meaningful 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?

Purpose is front-loaded, followed by scoping, behavioral caveats, and a parameter recap with example. The NOTE and REQUIRED/OPTIONAL/EXAMPLE blocks are dense but each earns its place; slightly verbose but not wasteful.

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 still conveys return-relevant fields (creative_count, coverage.empty_reason). For a read-only, zero-required-param list tool this is nearly complete; only connection_context is left unaddressed.

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

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

Schema description coverage is 0%, so the description must carry the burden. It documents parent_id well (str, UUID of parent folder, omit for top-level) but leaves connection_context entirely unexplained, so it only partially compensates for the coverage gap.

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 (creative folders) with scope (authenticated tenant, optionally parent_id-scoped). It distinguishes itself from the sibling creatives_list by clarifying that root creatives_list still returns READY_LOCAL files with folder_id=null.

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

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

Gives clear usage context: omit parent_id for top-level, and explicitly instructs the agent to inspect coverage.empty_reason before telling the operator the library is empty. It also warns that zero folders does not mean an empty library. It lacks an explicit 'use X instead of Y' routing statement, keeping it from a 5.

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

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

Annotations already declare destructiveHint=true and openWorldHint=false, and the description adds strong behavior: idempotency, fixed bounded concurrency, input-order preservation, and a data-disclosure guarantee (no storage keys, hashes, provider bodies, tenant IDs). It does not disclose the destructive side effects implied by destructiveHint=true (e.g., what storage state is altered or removed), which is the one behavioral gap.

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 and batch scope, then reason_code semantics, concurrency/security constraints, then the REQUIRED/EXAMPLE block. Dense but every sentence carries operational information; slightly packed given the single-paragraph run-on of constraints.

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, and the description compensates by describing the return shape (order preserved, redacted fields) and pointing at readiness.retryable/reason_code/next_action as the decision surface. Complete enough for invocation, with the only omission being the destructive side effect and connection_context.

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 0%, so the description must carry semantics; it constrains creative_ids to 1..20 unique IDs sourced from creatives_list and supplies a call example. The second parameter (connection_context) is never mentioned, though it appears to be a platform-wide context 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 ('reconcile ... creative IDs') plus scope (1..20 tenant-owned IDs, single server-side batch). It explicitly distinguishes itself from the sibling it could be confused with ('do not fan out creatives_confirm_upload calls').

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 (use readiness.reason_code to distinguish pending bytes, verification, terminal failure, create eligibility) and when-not-to-use ('do not fan out creatives_confirm_upload'), plus a retry condition ('Retry only when readiness.retryable=true and follow readiness.next_action').

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 and readOnlyHint=false, so the description adds valuable context beyond them: tenant ownership scoping, uniqueness constraint, and a note clarifying that updated_at means row last touched rather than content changed. It omits why the rename is destructive, but the annotation covers that warning.

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

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

The description is front-loaded with purpose and constraint, then uses compact NOTE/REQUIRED/EXAMPLE sections. Every sentence adds actionable information given the 0% schema coverage, with 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 no-output-schema tool with 0% schema coverage, the description is incomplete: it fails to document connection_context and gives only a partial hint about return values (updated_at semantics). It covers the core rename behavior and prerequisites but leaves notable gaps for an agent.

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

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

Schema description coverage is 0%, so the description must carry all parameter meaning. It documents the two required parameters with type and UUID format for folder_id and clarifies name is the new name, but it completely omits the third parameter connection_context.

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 'rename' and resource 'creative folder', and scopes it to folders owned by the authenticated tenant. Distinguishes from siblings like creatives_create_folder, creatives_delete_folder, and creatives_list_folders by its unique action.

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

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

No explicit statement of when to use this tool versus alternatives, but the rename action is self-evident and there is no sibling rename tool. It provides a usage prerequisite (name uniqueness within the same parent) but 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?

Goes well beyond the annotations (readOnlyHint=false, openWorldHint=false, destructiveHint=false): it discloses the idempotency requirement, the exact return branches, explicit negative scope ('never returns upload_url, r2_key, provider credentials, or raw tenant identifiers'), the required Authorization header, and the server-side enforcement set (mcp.launch.prepare, tenant ownership, rate limits, concurrency, size, type, R2-prefix checks). This is exactly the operational context an agent needs beyond the safety hints.

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

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

Front-loaded with the core purpose and the idempotency requirement, then negative scope, then the follow-up mechanics and the example. Dense but every sentence carries substantive information; the final enforcement list is long but load-bearing rather than 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 and only sparse annotations, the description compensates by documenting both return branches, the follow-up HTTP step, auth requirements, and enforcement behavior. An agent has everything needed to invoke it correctly and route the resulting bytes.

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 0%, so the description carries the full burden and does: file_size range (1..500MB), file_hash format (lowercase 64-hex), upload_attempt range (1..3, default 1), idempotency_key stability requirement, plus a concrete worked example. Only connection_context is left unexplained, a minor omission given the exhaustive coverage of the real inputs.

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: prepare or reconcile a tenant-owned creative upload. It clearly scopes the operation as a pre-upload step versus a byte transfer. It does not explicitly differentiate from the v1 sibling 'creatives_request_upload' or route to 'creatives_confirm_upload', so it falls short of full sibling disambiguation.

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 through the described lifecycle (call this first, then POST bytes to the returned endpoint), and it describes the two return branches (upload_endpoint when bytes are needed vs dedup_success for a ready object). However, it never names an alternative tool or states when-not to use this, so the agent must infer the flow position from the sibling list.

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 and openWorldHint=true. The description adds genuinely useful behavior beyond them: the single-use nature of approval_ref ('one'), the one-time execution guarantee, and the retry policy ('Uncertain writes are recorded and never auto-retried'). That retry disclosure is valuable context for a mutation tool.

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

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

Two tight sentences, zero filler, and the core action is front-loaded before the retry caveat. 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?

The behavioral story is solid for a destructive write tool with no output schema, but the 0% parameter coverage and the absence of any mention of connection_context or how to obtain an approval_ref leave the invocation path underspecified.

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 0%, so the description must carry the burden. It only implies approval_ref is a consumed single-use token, and says nothing about connection_context or the token's origin/format, leaving the optional parameter entirely undocumented in both schema and description.

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: 'execute the recorded delivery-status change' via an approval_ref. The prepare/confirm pairing is implied by the approval_ref and the sibling delivery_status_prepare, but the description never names that sibling, so an agent must infer the workflow relationship.

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 through 'Consume one approval_ref' and 'execute the recorded delivery-status change once', suggesting this is the second step after a prepare. However, it never states when to use this over alternatives like delivery_status_prepare or other *_confirm tools, nor any prerequisites beyond the token.

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 give readOnlyHint=false with destructiveHint=false, which is potentially confusing, and the description usefully resolves it: the tool writes an approval artifact but 'never mutates TikTok'. It also adds the 'bounded tenant-owned' scope and the single-use nature of the returned reference. It omits auth requirements, idempotency behavior, and validation failure modes.

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 behavior front-loaded and zero filler. Phrasing like 'bounded tenant-owned' is slightly opaque jargon, but nothing is wasted or 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?

The description conveys the essential model (validate, no mutation, return approval_ref), which partially compensates for the absent output schema. However, for a tool with 7 required parameters and no schema descriptions, leaving nearly every input unexplained is a real gap.

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

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

Schema description coverage is 0% across 8 parameters, so the description must carry the burden, yet it clarifies only entity_type (ad_group vs adset alias). run_id, rule_id_and_version, idempotency_key, entity_refs, target_status, ad_account_id, and connection_context are left entirely unexplained.

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

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

The description names a specific verb and resource ('Validate a ... TikTok delivery-status change') and states the artifact produced ('return a single-use approval_ref'). It also separates itself from the confirm counterpart via 'This tool never mutates TikTok', though it never explicitly names the delivery_status_confirm sibling as the downstream 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?

The only routing guidance is parameter-level ('Use native ad_group; adset remains an explicit adapter alias'), which addresses enum choice rather than when to call this tool instead of delivery_status_confirm or bid_prepare/budget_prepare. The prepare-then-confirm relationship is only implied by the name.

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: discloses the artifact_ref + one-hour download_endpoint contract, the 5 MiB cap, same-tenant credential requirement, the rule never to embed credentials in URLs, and the attribution options. The closing line 'this is not a read-only call' correctly reinforces readOnlyHint=false without contradicting it.

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

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

Purpose is front-loaded and the two paragraphs are dense with actionable constraints. There is mild redundancy between the return-value sentence and the closing 'private, expiring CSV artifact' line, but each statement still adds distinct operational guidance.

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 10-param export tool with no output schema, the description covers the return shape, auth model, size/time limits, and required inputs. The main gap is the required group_by parameter and search filter, which an agent must infer from the schema alone.

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 0% schema coverage the description carries the load and explains date_from, date_to, the ad_account_id/product_id scope choice, confirm_export, export_mode, and attribution semantics. However, group_by (a required enum of account/campaign/ad_group/adset/ad) and search are left unexplained.

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 ('Export insights as CSV') and immediately clarifies the two emission granularities (grouped per-entity totals vs. daily date/entity rows). The CSV-artifact framing makes it distinguishable from the many insights_* query siblings, though none are 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?

Gives concrete prerequisites (date_from, date_to, exactly one scope filter, confirm_export=true) and explains which export_mode to pick for which output shape. It stops short of explicitly routing the agent away from siblings like insights_query_rows or insights_pull_insights.

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 openWorldHint=false, so the agent knows this is a safe, closed read. The description adds that the result is tenant-scoped and reads from cache, which is useful. It doesn't say what happens on an empty cache, which would matter for bounding windows.

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 what is returned and followed by the intended use. 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?

For a trivial no-required-param read with annotations covering safety, the description is nearly complete: it says what is returned, scoped to the tenant, and why. Missing only empty-cache behavior, which is a minor 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 0% and the single parameter connection_context is undocumented in both schema and description. With one optional param and no facts to add, the description says nothing about it; a 3 reflects that no compensating meaning is provided but the param is likely internal plumbing.

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 resource (min/max stat_date in cache) for a scoped tenant. Clearly distinguishes itself from insights_query_overview, which it references as the consumer.

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 says to use it to bound query_overview windows, giving clear context. Does not name exclusions or alternatives beyond that, so it falls short of a 5.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered; the description adds real operational context beyond that — it is asynchronous, spawns one task per active connection, and returns legacy task_id values. It does not explain what the destructive flag actually affects (cache invalidation/overwrite cost) or how to poll the returned task_id, leaving a couple of behavioral gaps.

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

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

Purpose is front-loaded, and the REQUIRED/OPTIONAL plus EXAMPLE blocks are well-structured and immediately scannable. The middle sentence is dense with product jargon ('legacy task_id', 'Agent Method clients', 'opaque task_ref'), but no sentence 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?

There is no output schema and no schema descriptions, so the description carries the burden for an async, task-submitting tool. It states the return is a task_id but never tells the agent how to consume that id (e.g., the tasks_* polling siblings) and omits connection_context, leaving the workflow incomplete for a caller without prior product knowledge.

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 0%, so the description must compensate. It does so well for 'days' (range 1..90, default 30, and the key clarification that it is a window length, NOT a date pair), but 'connection_context' is never mentioned, so half the parameters remain undocumented in both the schema and the description.

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 ('Async refresh of cached insights from the TikTok Marketing API') and explains the mechanism (submits one pull_tiktok_insights task per active connection). It also explicitly distinguishes itself from the sibling insights_query_consistent, so an agent can route without opening either 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?

Names the alternative path explicitly ('Agent Method clients should follow the opaque task_ref returned by insights_query_consistent') and labels this the 'manual refresh compatibility path', giving a clear condition for choosing it. The guidance is framed around a specific client concept ('Agent Method clients'), which an arbitrary caller may not self-map cleanly, so it falls short of a fully general when/when-not statement.

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/openWorldHint/destructiveHint, so the safety profile is covered. The description adds real behavioral context beyond that: cache-only sourcing from tiktok_insights_daily, the 1-20 scope ceiling, and that custom attribution windows are rejected at the server.

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

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

Purpose is front-loaded, then attribution, required fields, date-param gotcha, and a concrete example, each on its own labeled line. Dense but zero waste, and the ordering matches how an agent would construct the call.

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-param, no-output-schema tool it covers the call-critical pieces (group_by, scopes, dates, attribution) and an example. It remains incomplete on pagination, sorting, view_mode and consistency, and the group_by/product_id discrepancies against the schema could actively mislead.

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 0% across 11 params, so the description must carry the load. It documents group_by, the scopes[] shape, and the date_from/date_to naming gotcha, but leaves page, page_size, sort_dir, sort_key, view_mode, consistency, connection_context and require_complete_range unexplained. Worse, it lists group_by as {account, campaign, adset, ad} (omitting the schema's ad_group) and claims a product_id scope filter that the schema explicitly does not expose.

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: a server-side batch overview that compares multiple explicit scopes, reading cache-only from tiktok_insights_daily. The batch framing inherently distinguishes it from single-scope siblings like insights_query_overview, but no sibling is named 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?

Gives clear context: use it for comparing multiple scopes without client-side concurrent fan-out, with constraints on attribution (omit or use value; custom windows rejected) and the 1-20 scope limit. It stops short of explicitly stating when to prefer this over insights_query_overview or insights_query_consistent.

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 flag destructiveHint=true and readOnlyHint=false, and the description corroborates rather than contradicts: 'May enqueue a data refresh, replace cached data and persist pagination state; this is not a read-only call.' It adds non-obvious behavior beyond annotations — single-use opaque continuation tokens, an ordered compact envelope, freshness acknowledgement deadlines, and the adset adapter alias — which materially changes how an agent must call it.

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

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

It is front-loaded with the core contract and each sentence carries distinct information (scope shape, pagination rule, freshness bound, polling behavior, side effects). The 'Canonical Agent Method Profile V1' framing and some compound sentences are jargon-heavy, but there is little pure 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 17-parameter, high-complexity tool with no output schema, the description covers the contract essentials: response shape, pagination protocol, freshness/polling behavior, scope cardinality, and destructive side effects. Remaining gaps are the consistency/freshness enum modes and date_range_mode/after_mutation_ref semantics, which matter for correct invocation.

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

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

Schema description coverage is only 6% across 17 parameters, so the description must carry the load and largely does: it explains scope vs. scopes (max 20), the ad_account_id requirement, ad_group vs. adset alias, min_as_of's narrow meaning, continuation and source_snapshot semantics, and effective page-size preservation. Several parameters (consistency, response_mode, date_range_mode, require_complete_range, connection_context) still get no explanation, keeping it short of 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?

The description states a specific operation (an insight read returning one ordered compact evidence envelope) and its input shape (one scope or one batch of up to 20 scopes), which is clearly more than the title. However, in a sibling cluster dense with insight tools (insights_query_rows, insights_query_overview, insights_query_batch_overview, insights_pull_insights), it never explicitly says what distinguishes this 'canonical' method from those, so an agent cannot route on name alone.

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 genuine operational guidance: start at page one, follow the single-use continuation serially when has_more=true, treat min_as_of only as a freshness lower bound, and poll task_ref / honor dependency_unavailable backoff for a wait_ms=0 fresh request. But it offers no when-to-use-this-versus-sibling guidance, and the 'one scope or one batch' choice is left implicit.

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?

Explains behavior the annotations cannot: the continuation is single-use, tenant-bound, pinned to the original route/query shape/page size/snapshot, and the call may persist the next page's continuation. This also reconciles the destructiveHint/readOnlyHint=false annotations, since consuming a single-use token mutates server-side pagination state.

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 purpose, then constraints and failure remediation. The trailing paragraph ('Consumes the single-use continuation and may persist the next page's continuation') restates the opening sentence and adds little, slightly diluting the otherwise tight structure.