VidGuy

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

Annotations give readOnlyHint=false and idempotentHint=false, but the description adds the critical non-obvious behavior: the source must be uploaded via this path and its key prefix is validated, plus the 2GB size cap. It doesn't cover URL expiration, so not a full 5.

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

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

Two dense sentences, front-loaded with the action and the exact field names to use (uploadUrl, r2Key), with the caveat parenthetical in the right place. No 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?

No output schema exists, so the description correctly names the return values an agent must use (uploadUrl and r2Key). It links to the next tool in the workflow. Missing details like URL TTL or failure behavior, but the essential handoff is complete.

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

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

Schema coverage is 33%, and the description adds the practical 2GB size ceiling that constrains fileSize. It does not clarify fileName/fileType semantics beyond what the schema shows. Baseline for partially documented params, with one useful added constraint.

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 presigned PUT URL for an AI Edit source video. Names the downstream sibling create_ai_edit and its own upload flow, distinguishing it from generic upload siblings like create_upload or swap_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?

Explicit sequence: get URL, PUT bytes to uploadUrl, then pass returned r2Key to create_ai_edit. Also gives a constraint (source must be uploaded this way; key prefix validated) that tells the agent when not to bypass this tool.

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

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

Annotations cover safety profile (readOnlyHint=false, destructiveHint=false). Description adds pricing ('FREE') and critical downstream usage ('pass as seedImageAssetId to generate_influencer_look or build_influencer_vault'), which the annotations don't provide. Doesn't describe failure modes for non-stable URLs, keeping it from 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 purpose, then cost, then prerequisites, then workflow. Every sentence carries useful information. Four sentences with some density but no fluff.

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, but description explicitly states the return value (vault asset id) and how to consume it downstream. Covers prerequisites, cost, and integration path. Nearly complete for a mutation 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 100%, so baseline 3. Description adds the constraint that imageUrl must be a stable public/hosted URL and that influencerId comes from create_influencer, and describes role via 'identity reference'. Slight value add above schema.

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

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

States a specific verb (Attach) and resource (user's own image as identity reference for an influencer). Clearly distinguishes from sibling create_influencer and generate_influencer_look.

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 names import_asset_from_url and create_upload as prerequisite paths depending on source (URL vs raw bytes). Also tells the agent when to skip the paid look preview. Strong 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 by disclosing that the operation SPENDS CREDITS (≈25 per b-roll clip plus a flat premium when starterBundle=true), that the exact amount returns as creditsReserved, that it is refunded automatically on failure, and that builds take several minutes. Annotations only flag destructive/openWorld; the cost, refund, and latency behavior is the real added 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-loads the core purpose and the credit warning, and every sentence carries information (async, cost, polling, duration, starter bundle). The caps emphasis and stacked clauses make it slightly dense, but there is no filler.

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

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

With no output schema, the description carries the return contract adequately: it returns a build job immediately with an id to poll. Cost, refund, latency, and the polling channel are all covered, so an agent has everything needed to invoke and follow up correctly.

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

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

Schema coverage is 82%, so the schema already documents most parameters. The description still adds meaning beyond it by explaining starterBundle's first-build pricing semantics and reinforcing the per-clip credit cost of brollCount, though turbo, resolution, and prompt get no extra description-level 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 (kick off an async build) and resource (influencer's vault), and enumerates exactly what the vault contains (character/reference sheet, on-camera stills, faceless b-roll, short clips). It also names the sibling polling tool get_influencer_vault_build, letting an agent distinguish it from generate_influencer_look or generate_influencer_studio_image 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 explicit conditions: poll get_influencer_vault_build until status 'completed', and pass starterBundle=true for the very first build after create_influencer. It warns not to poll as if instant. It does not, however, contrast usage against adjacent generation siblings (generate_influencer_look, generate_influencer_snack), so exclusions are only partial.

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

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

Annotations already declare readOnly/non-destructive, and the description corroborates rather than contradicts ('Read-only; this tool itself never moves money'). It adds substantial context annotations cannot convey: the 402 challenge flow, the exact payment headers (PAYMENT-REQUIRED, WWW-Authenticate), that the same request is retried with a payment header, and that credits land on settlement and never expire.

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

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

A single dense paragraph, but it is front-loaded with the highest-value fact (what the offer returns) and each subsequent clause carries actionable payment-flow detail. Slightly long and list-free for a multi-step flow that would benefit from 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 payment-negotiation tool with an output schema (so return shape need not be restated), the description covers everything an agent needs: what is returned, which rails exist, how to trigger the challenge, how to settle, and when the credit arrives.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantics beyond the schema: `required` originates from an insufficient-credits error and selects the smallest covering offer size, which clarifies the intended data source for that value.

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 the offer for a pay-as-you-go credit top-up') and enumerates exactly what the offer contains: the POST URL, the USD price, and the accepted rails. It is clearly distinguishable from sibling account tools like get_credits because it returns a payment offer rather than a balance.

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 triggering conditions: pass `required` when an insufficient-credits error blocks an action, or pass `credits` for a specific size. It never names an alternative sibling tool (e.g. get_credits) to route between, so it stops short of explicit when-not guidance.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavior: the 409 failure condition, the downstream side effect that scheduled posts are also cancelled on the publishing provider, and the cost ('Free'). It does not describe what happens to the row post-call, keeping it out of the top band.

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

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

Three short sentences, front-loaded with the action and post states, then the failure condition and side effect. No sentence is padding; even 'Free' carries cost information an agent may need.

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 rich annotations and a fully described single-parameter schema, the remaining burden on the description is behavioral, and it covers the error case, side effects, and cost. The only gap is the post-call state of the row (deleted vs. marked cancelled), which is minor for a cancel operation with no output schema.

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

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

Only one parameter (postId) exists and schema description coverage is 100%, so the schema already documents it as a social post UUID. The description adds no format, sourcing, or lookup guidance beyond that, making the baseline 3 correct.

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

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

The description states a specific verb (cancel/remove) and resource (social post) and enumerates the exact post states it handles: scheduled, draft, failed, cancelled. That state enumeration, plus the publishing exclusion, lets an agent distinguish it from siblings like retry_social_post or get_social_post 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?

It clearly states when the tool applies (scheduled/draft/failed/cancelled posts) and when it does not (posts already 'publishing' return 409). It stops short of naming an alternative for the publishing case or routing failed posts to retry_social_post, so it is strong context without explicit alternative routing.

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

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

Adds substantial context beyond the annotations: a 15–90s (up to ~4 min) synchronous latency profile, the fact that it never posts autonomously, and the review-board/owner-approval workflow for generated content. These are exactly the non-obvious traits (blocking behavior, side-effect boundary) that annotations cannot convey.

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

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

Front-loads the core purpose, then the side-effect boundary, then the latency warning last where it matters. Some parenthetical asides ('personality, posting accounts', 'approving posts') add length, but nearly every clause carries information.

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

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

For a no-output-schema, side-effecting tool, the description covers what happens downstream (content lands on the review board for approval) and the runtime cost. The remaining gaps are return-shape expectations and explicit sibling routing.

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 description does not compensate: it does not explain the influencerId format nor the 1–8000 character message constraint. Only the 'ONE message per call' hint indirectly constrains the message parameter.

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

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

States a specific verb and resource: talking to the influencer in their main Companion chat, with a concrete description of which agent/thread it touches. However, it never names or distinguishes itself from the sibling send_influencer_message, leaving the agent to infer the difference between 'chat' and 'send message'.

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 useful operational guidance ('send ONE message per call and wait') and flags that it is synchronous and slow, but never says when to prefer this over send_influencer_message, list_influencer_messages, or the agent-configuration siblings. Usage is implied rather than routed.

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 behavior beyond annotations: asynchronous execution returning a projectId, the polling requirement via get_job, an explicit credit spend with a per-30s formula and a broll surcharge, and the default-off b-roll flag. This is exactly the kind of cost and lifecycle disclosure a destructive, non-idempotent tool needs.

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

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

Three tight sentences front-load the capability first, then async behavior, then cost, then prerequisite. The telegraphic parenthetical style is efficient but slightly dense; nothing is wasted.

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

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

With no output schema and an async lifecycle, the description supplies the missing pieces an agent needs: return contract (projectId), polling path (get_job), cost model, and prerequisite upload. Enum value meanings, the largest remaining gap, are not covered.

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

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

Schema description coverage is only 25% across 12 params, so the description must compensate and it partially does: it explains sourceR2Key's origin, broll's default and cost, and that sourceDurationSeconds drives cost. However, the six enum parameters (recipe, editStyle, captionStyle, outputFormat, sfxIntensity, captionPosition) and name/notes remain unexplained, leaving notable gaps.

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 ('Polish uploaded footage') and enumerates the actual output features (captions, punch-ins, b-roll, SFX), which distinguishes it from generic create_video/create_ai_story siblings. It does not explicitly name a competing sibling, but the described capability is specific enough to route on.

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 preconditions (requires an r2Key from ai_edit_upload) and the follow-up action (poll get_job), plus the credit cost of running it. It does not state when to prefer this over other video-creation siblings, so it falls short of 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 cover the safety profile (destructive=true, non-idempotent, openWorld), and the description adds material context beyond them: the async job pattern with a get_job polling loop and the credit cost (50 short / 80 medium). That cost and the required public URL are exactly the side-effect facts an agent needs before spending credits.

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

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

Three tight clauses, front-loaded with the core purpose, then async behavior, then cost/prerequisite. No filler; every sentence carries needed information.

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

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

With no output schema, the description correctly discloses the return shape (jobId, poll via get_job) and the credit cost. Remaining gaps are minor — it doesn't say what the finished artifact is (a video) or clarify the platform enum's effect, but it is sufficient to invoke the tool correctly.

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

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

Schema coverage is 71%, so most parameters are already documented (prompt, duration, styleTemplateId, referenceImageUrl, styleReferenceImageUrl). The description reinforces referenceImageUrl must be public and ties 'short'/'medium' to scene counts, but adds little for the undocumented platform and name fields. Baseline 3 is appropriate.

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

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

States a specific verb and resource: 'Generate a dialogue-first short drama from a single reference image', with concrete scope (5-scene short / 9-scene medium). This is distinctive against generic siblings like create_video or seedance_generate_video, but it never names an alternative, so the differentiation is inferable rather than explicit.

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 operational context — 'ASYNC — returns a jobId; poll get_job until completed' and 'Requires a public referenceImageUrl' — which implies usage. However, it gives no when-to-use guidance against the many other creation tools (create_video, create_ai_edit, seedance_generate_video), leaving the agent to guess which generator to pick.

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

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

Annotations already declare the write/safety profile (readOnly=false, destructive=false, idempotent=false). The description adds genuinely new behavior: the operation is free (no credits), targetAudience is auto-derived if omitted, and the call returns the new brand's id. It could say more about what happens on duplicate names or failure, 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?

Four tight sentences, no filler; the core action and its precondition are front-loaded, and the return-value handoff to generate_snacks closes it usefully.

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 mutation with no output schema, the description covers the essentials an agent needs to call it correctly: cost, a key default, and the shape of the return (brand id). It leaves several optional params unexplained, but those carry types/limits in the schema and are not required for a correct call.

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 10 params, so the description carries a heavier burden. It compensates for two of them well – `description` must be a few sentences because short ones hurt content quality, and `targetAudience` is derived when omitted – but says nothing about language, industry, screenshots, appDemos, or the required-set nuance. Partial compensation at the baseline.

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

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

States a specific verb ('Register') and resource ('brand'), clarifies the domain concept ('one of your end-customers'), and conditions it ('when none of the existing brands fit'), which cleanly distinguishes it from get_brand, update_brand, and list_brands.

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?

'when none of the existing brands fit' tells the agent the precondition for using this over the read/list siblings, and the closing clause names the downstream consumer (generate_snacks). It stops short of explicitly telling the agent to call list_brands first, so it's clear context rather than a full decision rule.

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 indicate destructiveHint=true and readOnlyHint=false, implying mutation. The description goes beyond annotations by clearly stating the cost implications: cloning and image URL are free, while prompt generation spends 1 credit. It also reveals that library presets can be used directly, avoiding unnecessary clones, and that the return value is a characterId. This adds critical context for an agent deciding whether to call the 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?

The description is dense but organized: it starts with the core purpose, then lists the three modes in a clear structure, and ends with a usage caveat. It is a bit long but each sentence adds value; the only minor inefficiency is repeating 'saved for FREE' which 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?

Given the tool's complexity (three alternative inputs, cost implications, integration with other tools), the description is comprehensive. It covers prerequisites (import_asset_from_url), return value (characterId), and downstream usage (create_video). With no output schema, the description adequately explains the return value, and the annotations cover mutation/safety, so nothing essential is missing.

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

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

The schema already covers all parameters with descriptions, but the description adds significant meaning by explaining the parameter relationships (e.g., fromLibraryId defaults name/voice, imageUrl requires hosting, prompt requires a 9:16 portrait and costs a credit). It clarifies that name is optional in cloning context, which is not fully explicit in the schema.

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

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

The description clearly states the tool creates a saved character/actor for UGC video, distinguishes it from sibling tools like create_character_swap and list_character_library, and specifies the three input modes. It also explains the output (characterId) and its downstream use in create_video.

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 explicit when-to-use guidance: it details three mutually exclusive input methods (fromLibraryId, imageUrl, prompt), notes when to use import_asset_from_url for raw bytes, and warns against unnecessary cloning of library presets unless the user wants an editable copy, correctly routing to 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 flag a destructive, non-idempotent, open-world write, and the description adds substantial context beyond that: ASYNC execution returning a projectId, explicit credit costs per engine and resolution with minimums, and the +5 voice-change surcharge. The reusable-driving-key batching note is a genuinely useful behavioral trait not derivable from 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?

Front-loaded with the action and the ASYNC/credit warnings before the prerequisite detail, and each sentence carries distinct information. The dense parenthetical pricing stacks are justified but make it heavier than necessary.

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 13-parameter, credit-spending async mutation with no output schema, the description covers what an agent most needs: async contract, cost model, input provenance, batching strategy, and how to inspect or replay a result. Nothing critical to a correct first call is missing.

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

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

At 54% schema coverage the description compensates well for the cost-bearing parameters: engine pricing tiers, 1080p multipliers, per-section 3s minimums, and the source of each r2Key. It leaves name, prompt, sceneMatch, and saveAudio's actual effect unexplained (saveAudio is only covered in the schema), so the compensation is strong but not complete.

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: 'Swap a character image onto a driving video,' plus the optional range-preservation behavior. It is clearly distinguishable from siblings like swap_upload and swap_import_character, which the description explicitly relegates to input-preparation roles.

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 full call path: get the character r2Key from swap_import_character (existing image) or swap_upload (raw bytes), and the driving-video r2Key from swap_upload. It also names the follow-up tool (poll get_job) and the replay path (get_video), so the agent knows both prerequisites and next steps.

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 it is not read-only and not destructive, so the bar is lower. The description adds crucial context beyond annotations: it is free, plan-gated with specific limits (starter 1, pro 5, enterprise 10, free 0), returns the new influencer id, and cannot be idempotent as each call creates a new profile. This is rich transparency.

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-structured, front-loading the core purpose and cost. It uses multiple sentences efficiently, though the second sentence about attach_influencer_reference is slightly tangential to the creation act and could be separated as a note.

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

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

Given 7 parameters with 86% schema coverage, no output schema, and annotations covering mutability, the description completes the picture by stating cost, plan limits, return value, and next-step workflow. An agent has everything needed to invoke correctly and plan subsequent calls.

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 high at 86%, so the baseline is 3. The description implies the required 'name' parameter but adds no syntax or format details beyond what the schema provides. It does clarify the return value (influencer id) but that is not parameter semantics.

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

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

States a specific verb+resource ('Create a new persistent AI influencer identity') and maps it to the dashboard equivalent. It clearly distinguishes itself from siblings like generate_influencer_look and build_influencer_vault by noting those are the credit-spending steps.

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

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

Explicitly states when to use this tool ('FREE — this just creates the profile row') and names the alternative steps when the user wants the look or vault. It also provides a clear conditional workflow: 'To start from the user's own photo, call attach_influencer_reference next'.

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 ASYNC execution, that a jobId is returned, that get_job must be polled, that per-slide assets come via get_video, and that it spends ~20 credits. It does not explain what the destructiveHint implies operationally, but the async/cost/polling detail is strong added 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?

Three dense sentences with zero filler, front-loading what it produces before the operational details. Every clause earns its place, including the cost and polling instructions.

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

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

With no output schema, the description carries the return-path burden and does so (jobId → get_job → get_video). For a 4-param, credit-spending generation tool the async flow, cost, and input prerequisite are covered; only the platform/name params are left to the schema.

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

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

Schema coverage is 50% and the schema already documents prompt and referenceImageUrl. The description reinforces the reference-image requirement ('public referenceImageUrl', 'single reference image') but adds nothing for name or platform, so it stays at baseline.

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

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

States a specific verb (generate), a precise resource (portrait 5-slide deck), and a scoping constraint (varied from a single reference image). This is distinguishable from siblings like create_video and studio_generate_image 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 clear prerequisites (requires a public referenceImageUrl) and cost guidance, but never names an alternative or states when-not to use it. The agent can infer prerequisites but not how to choose this over the other creation tools.

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

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

Beyond the destructive/openWorld annotations, it discloses that posts go to live external platforms, that the call is not retried server-side and needs distinct content per call, the 402 entitlement failure mode, and that it is free (no credits). This is exactly the operational context annotations cannot express.

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

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

It is a dense single block but front-loads the core purpose and every clause carries functional information (conditional URL rules, timing logic, drafts, failure modes). It could be broken into clearer segments, but there is little 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 15-parameter mutation tool with nested objects and no output schema or schema descriptions, it covers the highest-risk behaviors (live posting, entitlement 402, no retry, timing modes). It leaves several parameters and the return shape unexplained, but the safety-critical context is present.

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 explains the assetKind-to-URL conditional rules, scheduledAt/addToQueue exclusivity, and the platformOverrides post_mode draft trick well. However, many of the 15 parameters (title, tags, visibility, saveAsDraft, thumbnailUrl, accountVariants, first_comment) receive no mention, so it compensates only partially.

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 pair (publish/schedule), the resource (post), the target (connected accounts on a brand), and the fan-out scope in one call. An agent can distinguish this from siblings like create_tiktok_carousel or publish_to_managed_account 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 explicit when-to-use rules for the timing modes (omit both to publish now, scheduledAt for a time, addToQueue for the queue, mutually exclusive) and points to get_video/import_asset_from_url/create_upload for sourcing URLs. It stops short of naming alternative siblings or when-not-to-use cases, so it is clear but not fully routing.

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

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

Annotations declare the write/destructive/open-world profile, and the description goes well beyond them: credit cost per carousel, async job lifecycle and where slide URLs land, the fact that copy is real text rather than rendered pixels, and the non-obvious behavior that unknown `values` keys are reported in ignoredKeys instead of rejected. That ignoredKeys detail is exactly the kind of silent-failure context an agent cannot get from 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?

Front-loaded with the core purpose, then constraints (async, credits, max rows), then the optional image-generation recipe. It is long, and the embedded studio_generate_image prompt example is the one passage that reads as instruction rather than tool definition, but nearly every clause carries operational value.

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

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

For a high-complexity, credit-spending, destructive, async tool with no output schema, the description covers the return contract (jobId plus slide URLs on the job), cost, limits, key validation behavior, and the image-slot formats. Nothing an agent needs before invoking it is missing.

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

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

Schema coverage is 80%, so the baseline is 3; the description adds genuine semantic meaning on top — `values` keys must originate from list_carousel_templates (schema only says 'Keyed by the template's rowSchema keys'), image slots accept either a `collection:<pool>` reference or a direct URL, and the 12-row cap is restated. Seed and noRepeatScope are left to the schema, hence not a 5.

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

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

Opens with a specific verb and resource: 'Render a batch of TikTok photo carousels from a template', then narrows the artifact ('swipeable 1080x1920 slides, real library photos, copy composited as REAL text'). This is clearly distinguishable from siblings like create_slides, create_video and create_social_post 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 states the async workflow ('returns a jobId; poll get_job until completed'), names the prerequisite tool for key discovery (list_carousel_templates), names the alternative generation path for backgrounds (studio_generate_image with specific modelKey and prompt recipe), and gives hard limits (max 12 per call). When/when-not and alternatives are all present.

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

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

Annotations only declare the safety profile (readOnly=false, destructive=false). The description adds the essential workflow context they lack: a two-step process, that bytes must be PUT with a matching Content-Type, and that the returned key can serve as an r2Key. This is real behavioral disclosure beyond 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?

Two dense sentences with zero waste, front-loading what the tool returns before the mechanics and the alternative. Every clause carries actionable information.

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

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

With no output schema, the description takes on return-value disclosure and does it well (uploadUrl, publicUrl, returned key), and it closes the loop on where the result goes. Nothing an agent needs to invoke 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 coverage is 50%: contentType is documented and filename is not. The description reinforces the Content-Type matching requirement but adds nothing about filename beyond the schema's length constraints, so the baseline 3 for schema-carried semantics 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 action (get a presigned PUT URL) and resource (upload target for image/video/audio), plus what is returned (uploadUrl and publicUrl). It is clearly distinguishable from the closest sibling, import_asset_from_url, which is explicitly named.

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

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

Explicit when-to-use and when-not-to-use: 'Prefer import_asset_from_url when you already have a URL.' It also routes the output to named downstream consumers (transcribe_media, create_voice_clone samples, voice_enhance), giving the agent the full context for choosing this tool.

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 (destructive/openWorld/non-idempotent) by disclosing the credit cost range (~50–200, dynamic, returned as creditsReserved), the async jobId/poll lifecycle, automatic credit refund on failure, and the 'auto' actor-pick side effect plus the characterId/actorPick response fields for campaign persistence. This is the mutation-cost and side-effect detail an agent needs before spending credits.

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

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

Front-loaded with the async+credit warning, then the UGC requirement, then the follow-up action. Dense parentheticals are all load-bearing (cost range, allowed UGC types, actorPick fields) 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, the description still covers the return contract (jobId, creditsReserved, characterId + actorPick) and the async polling path. Combined with the rich behavioral caveats, an agent has everything needed to invoke and then follow through.

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 63%, and the description compensates on the highest-risk params: videoType's UGC subset, characterId semantics ('auto', saved actor, persistence), and duration→credit mapping. It adds little on platform enum, scenePrompt, or additionalInstructions, so it is strong but not exhaustive.

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

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

Opens with a specific verb+resource+mode: 'Kick off an ASYNC full video production job (the Quick Create flow)'. It names the flow variant, which separates it from sibling generators like create_ai_story, create_ai_edit and studio_generate_video, so an agent can route 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?

Explicit conditional routing: UGC video types ('ugc','brainrot','ugc-broll','ugc-demo') REQUIRE a script and characterId, with the alternative sources named (list_characters / list_character_library) and 'auto' described as the fallback. It also states the follow-up step (poll get_job until completed).

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-idempotent, open-world write, and the description goes well beyond them: an explicit cost (SPENDS 5 credits), mandatory consent attestation with a 'never attest on your own' warning, rate limits (3 new per 24 h) and plan caps (Starter 2 / Pro 5 / Scale 15). These are exactly the irreversible-cost and authorization facts an agent needs before calling.

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

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

Front-loads the purpose, then cost, then the consent gate, then limits, in descending order of importance. The parentheticals are dense but every clause carries actionable constraint information; nothing is redundant with the schema or annotations.

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

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

For a nested-object, 6-parameter, no-output-schema mutation, the description supplies the consent sequence, cost, plan/rate limits, and sample constraints an agent needs to invoke it correctly. The only undetailed element, exact return shape, is implied by the stated voiceId usage.

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 50% schema coverage, the description compensates heavily for the key samples parameter: count (1-25), size cap (≤10 MB each), accepted sources (r2Key from create_upload/import_asset_from_url or direct https URL), and quality guidance (1-3 minutes of clean speech). It leaves name, description, languageCode and removeBackgroundNoise unexplained, but those are 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?

Names a specific verb (Create) and resource (instant voice clone / ElevenLabs IVC), making it trivially distinguishable from sibling creation tools like create_character or create_influencer. The scope (this account only) and downstream consumer (generate_speech voiceId) further pin down what it produces.

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

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

Provides an explicit prerequisite workflow (call get_voice_consent_statement first, show it, only proceed after in-conversation confirmation), states a hard exclusion (not on the Agent plan), and routes sample acquisition to create_upload / import_asset_from_url. It even names the downstream tool for using the result, so alternatives and conditions are fully covered.

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: it specifies that approving POSTS REAL CONTENT to each card's accounts, that this is the human-in-the-loop gate, how scheduledAt behaves differently for hosted vs connected accounts, that request_changes requires a reason, and that the reason reaches the influencer's chat. The destructiveHint=true annotation is confirmed with concrete, actionable detail rather than merely repeated.

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

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

A single dense paragraph, but front-loaded with the purpose and id source before the safety constraint and the per-mode semantics. Every sentence carries information; only the em-dash nesting of scheduling rules makes it slightly harder to scan.

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, open-world mutation with no output schema and 40% param coverage, the description covers the critical ground: irreversibility of posting, the human approval prerequisite, scheduling semantics, batch limits, and the fact that results are reported per-draft. Nothing an agent needs to call this safely 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?

With only 40% schema description coverage, the description compensates well: it defines approve/reject/request_changes behavior, the reason requirement for request_changes, the 1-20 draftIds batch limit, and the hosted-vs-connected semantics of scheduledAt. It adds meaning beyond the schema's terse 'ISO-8601 go-live time instead of now', though influencerId itself is only implicitly glossed.

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 ('Decide an influencer's review-board drafts') and immediately names the id source (get_influencer_agent → drafts.pending), which no sibling tool shares. An agent can distinguish this from get_influencer, chat_with_influencer, or publish_to_managed_account 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?

Explicit when-to-use and when-not-to-use: only after the user has seen the drafts and explicitly said which to approve, and never on the agent's own judgment. It also spells out the three decision modes and the consequence of each, leaving nothing 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, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description nonetheless adds genuinely useful cascade behavior beyond the annotations: referencing snack posts survive and their brandId is nulled. It could still say whether the operation fails if the brand is in use or what the response contains.

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

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

Three short sentences, front-loaded with the action and immediately followed by the two facts an agent most needs (cascade behavior, irreversibility). No filler or repetition.

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

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

For a one-parameter destructive tool with full annotation coverage and no output schema, the description supplies everything material: what is deleted, what happens to dependent data, and that it cannot be undone. 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 100% and there is a single required parameter already documented as 'Brand UUID' in the schema, so the description adds no parameter meaning. Baseline 3 for a fully documented single-param schema.

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

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

States a specific verb (delete) and resource (brand) unambiguously, distinguishing it from sibling deletes like delete_managed_post and delete_influencer_studio_image by resource. The follow-up sentences clarify the scope of the deletion's side effects.

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

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

Usage is only implied: the description makes clear this is a destructive, irreversible removal, but it never says when to prefer delete_brand over alternatives such as update_brand or simply leaving the brand intact, nor does it mention prerequisites like ownership or permissions.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false. The description adds genuinely useful context beyond those: only the gallery row is removed while the underlying file and any promoted vault copy survive, which materially changes how an agent should reason about the delete's blast radius.

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

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

One front-loaded sentence that states the action, the keys, and the scoping caveat with 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 destructive single-row delete with no output schema, the description adequately covers what is removed and what is preserved. Minor omissions (auth/permission needs, behavior if the id matches nothing) keep it short of full completeness.

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 parameter meaning. It adds that generationId is preferred over url as the lookup key, which is real guidance, but it says nothing about the required influencerId or any value formats, leaving a meaningful 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 (remove/delete) and resource (influencer studio gallery row) and identifies the two lookup keys. It is clearly distinguishable from siblings like list_influencer_studio_images and generate_influencer_studio_image.

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

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

The description gives a preference between parameters ('generationId (preferred) or url') which implicitly guides invocation, but never states when to use this tool versus alternatives or any preconditions. 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?

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds preconditions and failure semantics the annotations cannot express: published posts return 400, hosted-account posts return 409 with support instructions, and the operation is 'Free'. This is materially useful context for a destructive 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?

Three tight sentences, front-loaded with the core constraint (scheduled-only) before the edge cases. Every sentence carries a distinct, load-bearing fact 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 two-parameter destructive tool with no output schema, the description covers the preconditions, the two distinct error outcomes, and the account-type nuance. Nothing an agent needs to invoke this correctly or interpret failure is missing.

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

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

Schema coverage is 100% — both accountId and postId are documented in the schema, including the pointer to list_managed_posts. The description adds no new syntax or format detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Delete a managed post') and narrows the scope precisely to one that 'is still scheduled (queued, not yet live)'. This distinguishes it from siblings like cancel_social_post and delete_brand without requiring the schema to be opened.

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 gives the when ('still scheduled'), the when-not ('Once a post has published it can no longer be removed'), and the account-specific exclusion ('On hosted accounts a submitted post is already a work order... cannot be withdrawn through the API'). It even routes the agent to the correct fallback ('contact support').

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 idempotentHint=true, but the description adds important context beyond them: deletion is permanent, it removes both the stored transcript and its job, and it is free. It does not, however, discuss recovery, authorization, or failure 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?

The description is a single front-loaded sentence with no wasted words. The parenthetical clarification about what gets destroyed is compact and useful.

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 one-parameter destructive tool with rich annotations and no output schema, the description is nearly complete: it states permanence, what is deleted, and cost. The main missing piece is parameter guidance for transcriptionId.

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 single required parameter 'transcriptionId' is not explained in the description. The phrase 'a finished transcription' implies what is being targeted but does not clarify the identifier's format, source, or usage.

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: permanently delete a finished transcription, and it clarifies scope by identifying the stored transcript and its job. This distinguishes it clearly from sibling read/list tools such as get_transcription and list_transcriptions.

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 destructive verb and the qualifier 'finished transcription', but the description does not explicitly say when to use this versus alternatives, nor does it mention prerequisites or exclusions. It is adequate but lacks routing guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description still adds real beyond-schema context: the deletion propagates to ElevenLabs (external side effect) and consumes/returns a clone slot, plus a cost note ('Free'). It stops short of stating irreversibility or what happens if the voice is currently in 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?

Three very short sentences, the core action front-loaded, and each fragment carries distinct information (scope, external propagation, slot effect, cost). Nothing is padded.

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

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

For a destructive operation with no output schema, the definition covers the key consequence but omits reversibility, failure conditions (e.g., voice in use by an active job), and any confirmation/idempotency nuance beyond the annotation flag. Adequate but with clear gaps.

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 the single required voiceId parameter, so the description carries the full burden and does not meet it — no format, source, or lookup hint is given. The only implicit signal is 'one of your voices', which weakly constrains it to owned voices.

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

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

Specific verb 'Delete' plus resource 'voice', with an explicit scope qualifier ('one of YOUR voices'). The parenthetical that the underlying clone is 'removed from ElevenLabs too' distinguishes it from sibling tools like get_voice/list_voices/create_voice_clone and tells the agent the deletion propagates to an external provider.

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?

'Frees a clone slot' implies the motivation for using it, but there is no explicit when-to-use / when-not-to-use guidance and no named alternative (e.g., create_voice_clone / list_voices) that would help an agent route correctly. Usage is inferable rather than stated.

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

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

Delivers rich behavioral context beyond annotations: async nature with a returned dubbingId, the polling follow-up, and the 10-credit cost. This is exactly the operational detail annotations (destructiveHint, openWorldHint) cannot convey.

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

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

Front-loaded with the core action, then async behavior, cost, and enum codes in a compact span. Every clause carries information, though the trailing code list is somewhat dense.

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 2-param async tool with no output schema, the description supplies the missing pieces an agent needs: async pattern, follow-up tool, cost, and valid inputs. Nothing critical is absent.

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

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

Schema coverage is 100% and both parameters are fully described in the schema, so the description's enum listing of targetLang codes merely repeats structured data. Baseline 3 is appropriate.

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

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

States a specific verb (dub) and resource (a COMPLETED project's video into another language), plus the provider (ElevenLabs). Distinguishes itself from siblings like get_dub_status and create_video.

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 constrains usage to COMPLETED projects and directs the agent to poll get_dub_status afterward, which is clear operational guidance. It does not name when not to use it versus alternatives, but the workflow routing is strong.

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

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

Annotations cover readOnly and non-destructive hints, but the description adds crucial context: 'No credits spent, no I/O' clarifies it's a pure estimation with no side effects. The pricing formula (base 25, -7 for excluding ai-ugc, +3 for server render) is valuable behavioral detail not in annotations.

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

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

Two tight sentences: the first states purpose and timing, the second gives the cost model and side-effect guarantee. No wasted words, front-loaded with the key distinction.

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 2-param tool with an output schema, the description provides sufficient context: purpose, cost formula, and no-side-effect guarantee. The output schema presumably details the return value, so no need to explain it here.

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 that 'exclude' affects cost (saving 7 credits when excluding 'ai-ugc') and that 'render' adds 3 credits, giving meaning to both parameters 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?

States a specific verb and resource ('Estimate the credit cost of a snack generation') and explicitly distinguishes timing ('BEFORE running it') from the sibling generate_snacks. An agent can immediately tell this is a dry-run cost estimator.

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 positions the tool as a pre-flight check before generation, implying when to use it versus generate_snacks. However, it doesn't explicitly name the alternative or exclusion conditions, leaving some inference to the agent.

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 past the annotations: per-ad credit prices, the +1 render surcharge, the site-read credit, refund rules for unproduced or failed ads, and the async timing (15-30s site read, ~1-3 min generation, poll get_job). Consistent with destructiveHint=true and openWorldHint=true since it spends credits against a live fetch. Minor gap: it doesn't say what happens on an unparseable or JS-heavy page beyond the 'no usable product photo' refund example.

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 and mode selection, which is correct, but the middle is an undifferentiated block mixing cost tables, per-type prose, and async notes in one paragraph. Given 12 params and a real credit model the length is defensible, but it would scan far better as separated mode/cost/lifecycle segments.

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

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

Given an output schema exists, the description needn't describe return values, and it uses the freed space for the things the schema can't carry: async lifecycle, polling target (get_job), cost accounting, refund behavior, and mode selection. An agent can invoke this correctly on the first attempt.

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 already 92%, and the description still adds real value: mode exclusivity between `slots` and types/count/adFormats/animationStyle, what `slots.inputs` means (verbatim text vs auto-written from page), and what `prompt` steers (theme, audience, angle, music genre). Undocumented here are `name` and `language`, but the schema covers both adequately.

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 (generate paid-social ads from a URL) and enumerates the exact URL classes accepted: store, product page, service site, App Store/Google Play listing. It also names the source of truth (real products, prices, reviews on the page) and the two construction modes, so an agent can separate it from create_video, generate_meme, or create_social_post 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?

Explicitly routes between the two mutually exclusive paths — `types` (+count/adFormats/animationStyle) versus `slots` — and states the constraint that slots can't be combined with the others. It names the prerequisite sibling (call list_ad_formats first), documents the default pack when neither is supplied, and reports the plan eligibility (Pro, Scale, Agent).

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 information annotations don't carry: it costs 1 credit, credits are refunded on failure, and it returns both a preview image and a vault asset id. This meaningfully supplements the destructive/non-idempotent/openWorld hints. It stops short of disclosing any rate limits, auth requirements, or generation latency.

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

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

Four sentences, each carrying distinct payload: purpose/ordering, cost/refund, return shape, and the reference-photo workflow. The key scoping constraint is front-loaded and nothing is 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?

With no output schema, the description still names what comes back (preview image plus vault asset id), and it covers the pre-build approval intent, credit behavior, and the reference-anchoring prerequisite. An agent has everything needed to sequence and invoke it correctly.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds workflow meaning: seedImageAssetId comes from attach_influencer_reference and anchors identity to the user's own photo. That is value beyond the schema's field-level descriptions.

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

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

States a precise verb+resource ('generate a single cheap look preview portrait for an influencer') and explicitly scopes it as a pre-approval step distinct from the full vault build. Repeating that the vault later seeds from this look makes the tool's role unmistakable.

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 BEFORE the full vault build so the user can approve the face, and gives a concrete prerequisite chain: call attach_influencer_reference first, then pass its returned asset id as seedImageAssetId. Both when-to-use and the alternative (vault build) are 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?

Goes well beyond the annotations: declares async execution, credit spend backed by creditsReserved with refund-on-failure, a 10 packs/hour rate limit, the jobId return and polling contract, and a ~2 minute minimum completion time. This is unusually rich disclosure for a mutation tool whose destructiveHint/openWorldHint annotations only sketch the risk profile.

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?

Long but front-loaded, with the async nature and personality scoping stated first and operational facts (credits, rate limit, polling cadence) grouped after. Every sentence carries load, though the parenthetical onboarding note and capped emphasis 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 carries the return contract itself (jobId, poll get_influencer_snack until 'completed') plus latency and error behavior, so an agent has everything needed to call and follow up 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 100%, so the schema already documents count, types, exclude, prompt and influencerId. The description adds no per-parameter syntax or defaults, so the baseline of 3 applies.

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

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

States a specific verb and resource ('generate an ASYNC snack content pack in the voice of a specific influencer') and explicitly distinguishes itself from the brand-scoped sibling generate_snacks. The parenthetical mapping to the '+ New content' UI action further disambiguates it.

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

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

Gives explicit when-to-use context (influencer-scoped generation), removes a common blocker ('you do NOT need to attach a brand first'), states the only failure condition, and names the alternative sibling it is scoped against.

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 annotations by disclosing the model (Nano Banana 2 Lite), cost (1 credit), synchronous execution with typical ~10–30s latency, that the asset URL is returned in the result, that results land in the studio gallery, and how keepers reach the vault. This is exactly the operational context annotations cannot convey.

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

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

Front-loaded with the key operation, model, cost, and sync behavior before the usage guidance. Dense but nearly every clause carries signal; only the vault-promotion note is somewhat peripheral to calling the 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 compensates by saying the asset URL is in the result and where the asset is stored. Combined with annotations covering the mutation profile, an agent has enough to invoke correctly, though aspectRatio guidance would complete it.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It does this well for prompt and referenceImages (up to 4, https or data URLs, suggested uses), but aspectRatio's enum and influencerId's UUID format/role get no explanation, leaving two of four params undocumented anywhere.

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 ('Generate ONE on-identity image of an influencer') and implicitly separates itself from siblings like studio_generate_image or seedance_generate_image by calling out the server-side character reference injection that makes the output on-identity. An agent can tell this is the influencer-scoped generator.

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 strong intra-tool guidance ('describe the SCENE, outfit, or action, not the person') and clarifies how referenceImages are used, but never states when to prefer this over adjacent tools such as generate_influencer_look or studio_generate_image. Usage context is implied rather than compared against 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?

Adds substantial behavior beyond the annotations: async jobId return, ~1-3 minute latency, per-type credit costs, automatic refunds on failure, and silent per-slot skipping. The destructiveHint=true is sensibly explained by the credit-charging language, though the description never explicitly frames credit spend as the destructive aspect, leaving that inference to the reader.

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?

Opens with the core action, then layers modes, cost, optionality, and async caveats in a single dense paragraph. Despite its length, every clause conveys operational information an agent needs, and non-obvious pitfalls (silent skips, refunds) are front-loaded where relevant.

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-parameter, async, credit-consuming, open-world generation tool this leaves nothing material unstated: it covers mode selection, cost, refund behavior, polling, latency, and partial-result risk. With an output schema present, the description does not need to document return fields and rightly skips them.

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 already 100%, yet the description still adds real meaning: count is bounded 1-5 and cautioned that fewer may land, brandId's omit-vs-pass semantics are spelled out, each enum value carries a credit cost and behavior, and prompt is illustrated with concrete source examples (changelog line, blog title, launch note).

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 (create) and resource (memes) plus the input modality (plain-language prompt) and enumerates the three distinct modes. An agent can immediately tell this apart from studio_generate_image, seedance_generate_image, and create_slides, which are the nearest media-generation 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 describes when to choose each memeType (edit vs greenscreen vs comic), when to include brandId (with a pointer to list_brands) versus omit it, and how to operate the async flow (poll get_job). It even pre-empts the common confusion that the caller must supply the joke.

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

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

Annotations already declare it mutating, non-idempotent, and destructive, but the description adds substantial value beyond them: credit cost range (18–26), automatic refund on failure, async jobId return, and the semantic difference between render=true and a layered manifest. Strong disclosure; slightly short of 5 only because it doesn't clarify what 'destructive' means here (overwrite/replace 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?

Dense but front-loaded with the highest-priority facts (async, spends credits, needs brandId), and each subsequent sentence carries a distinct operational detail: timing, render, refunds. No filler sentences.

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 an output schema present, return values need not be re-described, yet the description still covers the async workflow, cost, prerequisites, and failure handling. Nothing an agent needs to invoke and follow up on this tool 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 coverage is 86%, so the baseline is 3, and the description earns above that by explaining the credit impact of parameters (render +3 credits, excluding 'ai-ugc' saves 7) and the consequence of the render toggle on what the user sees. It does not explain influencerMode/influencerId interplay beyond what the schema says.

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

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

Opens with a specific verb+resource+mode: 'Kick off an ASYNC snack generation job for a brand.' This distinguishes it from siblings like generate_influencer_snack or estimate_snack_cost without the agent 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 routes the agent: call estimate_snack_cost first, call list_brands or create_brand to obtain brandId, and poll get_job afterward. It states when render is appropriate and sets the 2–3 minute expectation, which is genuine when-to-use guidance.

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

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

Annotations declare a mutating, credit-consuming, non-idempotent operation, and the description substantiates that with real behavioral detail: exact output artifacts (MP3 audioUrl, r2Key reusable as a source in other tools, word list), the 1-credit-per-500-character cost, the 5000-character ceiling, the absence of speed control, and how inline tags like [laughs] are performed but excluded from timings. This is context the 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?

Dense but front-loaded, using SYNC/voiceId/Models labels to make it scannable, with the highest-value facts (output artifacts and cost) leading. A few clauses are tightly packed but none 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?

For an 8-parameter paid generation tool, the description covers the deliverables, the cost model, the limits, model selection, and tag behavior. The remaining gap is the numeric style/stability/seed parameters, which neither the schema nor the description explains, but an output schema exists so return-value detail is not required.

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 25% across 8 parameters, so the description must compensate, and it does explain voiceId sources, modelId options, and text length. However it says nothing about seed, style, stability, similarityBoost, or languageCode, leaving half the tuning surface 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+resource (text-to-speech generation) and immediately narrows scope by highlighting the word-timestamp output that distinguishes it from plain audio generators like studio_generate_audio or voice_enhance. An agent can tell what it produces without opening the schema.

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

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

Gives clear routing for voiceId (list_voices, or scope 'premade') and states cost and character limits up front, so the agent knows the preconditions before calling. It does not, however, contrast itself against the many overlapping audio siblings (studio_generate_audio, voice_enhance, dub_video), so the when-not guidance is incomplete.

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 nothing beyond the annotations – no note on what happens if the id is missing (error? empty?), no auth context. With annotations carrying the safety burden, some added value would be expected, but none is present.

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

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

One front-loaded sentence, no waste. Appropriately sized for a simple single-fetch 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 1-param read tool with full schema coverage and annotations, a minimal description is largely sufficient. However, no output schema exists, and the description doesn't describe what a brand contains, so an agent doesn't know the return shape.

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

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

Schema coverage is 100% and the schema documents brandId as a UUID. The description doesn't add syntax or format details beyond the schema. Baseline 3 when the schema does the heavy lifting.

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

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

States a specific verb (Fetch) and resource (brand) with scope (single, by id). Clear enough to distinguish from list_brands and get_influencer, though it doesn't explicitly name those siblings.

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

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

Implied usage: fetch one brand when you have its id. No explicit when-to-use vs list_brands or pointers to alternatives. Adequate but minimal guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered; the closing sentence ('never changes the agent or its work') largely restates that. The real added value is the inventory of what the payload contains (tasks, runtime/budget, recent runs, messages, knowledge, source files, review clips, Editor projects, Spy signals), which is meaningful given no output schema.

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

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

Front-loaded with the verb+resource, then the prerequisite, then the read-only guarantee. The long enumeration of returned data is dense but earns its place since there is no output schema; only the near-redundant restatement of the read-only hint 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?

With no output schema, the description usefully characterizes the return payload and the id-resolution path, which is enough to call this read tool correctly. It could go one step further by distinguishing itself from get_influencer_agent, which is the main remaining gap.

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

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

Schema coverage is 100% and the schema already documents agentId as a UUID from list_content_agents. The description repeats the same provenance, adding no format or edge-case detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (fetch) and resource (content-team agent) plus scope (by id, with full read-only dashboard context). It also enumerates the returned surface areas and distinguishes itself from list_content_agents, so an agent can identify 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?

Explicitly instructs 'Call list_content_agents first to resolve the id', which is concrete prerequisite guidance. It does not, however, address when to prefer this over the sibling get_influencer_agent, so the when-not case is left to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, and the description's 'Read-only; no credits spent' largely restates that. It adds little behavioral detail beyond annotations, though it does indicate the response includes plan allotment and recent transactions, which is useful framing.

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: the first defines the payload, the second gives the triggering condition. The scoping and safety note are front-loaded rather than 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?

Annotations cover the safety profile and an output schema exists, so the description doesn't need to explain return values. For a zero-required-parameter read tool, 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 100% and the single optional 'limit' parameter is fully documented in the schema, so the description need not restate it. It adds no syntax or default guidance beyond what the schema supplies, matching the baseline.

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

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

States a specific verb and resource ('Check the account's current credit balance, plan allotment, and recent credit transactions'), which cleanly separates it from siblings like buy_credits and estimate_snack_cost. An agent knows exactly what it retrieves 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?

Explicitly says when to call it ('before a credit-spending generation') and names the specific spending tools it should precede (create_video, generate_snacks, studio_*, seedance_*, etc.). This is a model routing instruction rather than vague context.

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 indicate a destructive, non-read-only action. The description adds meaningful side effects: contacting the provider, storing the dub, replacing the project asset reference, and potentially refunding the original charge. No contradiction with 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?

Three concise sentences, front-loaded with the core purpose and followed by the important side effects and output behavior. No filler or redundant wording.

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 covers the important output states and the post-completion videoUrl behavior, and explains both completion and failure side effects. It is complete enough for an agent to invoke the tool, though it does not describe the exact response shape.

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

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

Schema coverage is low at 33%: only dubbingId has a description and it is minimal. The tool description does not meaningfully explain projectId or targetLang, and does not compensate for the missing parameter 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?

The description states a specific action (poll and finalize) and resource (a language-dub job), enumerates completion/failure behavior, and explicitly says it does not start a new dub, which distinguishes it from dub_video.

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 this tool is used after a dub has started and clarifies it will not start a new one. However, it does not explicitly name the alternative tool or state additional conditions such as 'do not use if you need to create a dub.'

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 the shape of the returned profile (persona, visual identity, voice, status, metadata), which is useful since there is no output schema, but it discloses no further behavioral traits such as error conditions or permissions.

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

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

Two short sentences, front-loaded with the action and resource, followed by the routing prerequisite. No filler and nothing 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 single-parameter read-only getter, this is complete: annotations cover safety, the schema covers the id, and the description covers the returned fields in lieu of an output schema and points to the discovery 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 100% and the single influencerId parameter is already documented in the schema as coming from list_influencers. The description's 'by id' and provenance note therefore add no meaning beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb (fetch) and resource (one influencer profile by id) and enumerates the profile contents (persona, visual identity, voice, status, metadata). This clearly separates it from sibling list_influencers, which returns collections rather than a single profile.

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 the prerequisite workflow and the alternative source of the id: 'Call list_influencers first to get the id.' An agent knows both when this tool applies and where to obtain the required input without opening another schema.

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

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

Annotations already declare readOnlyHint/destructiveHint/openWorldHint, so the trailing 'Read-only' is largely redundant. However, with no output schema, the description does the heavy lifting by disclosing the shape of the payload (counts per status, pending review-board cards with caption/media/target accounts), which is exactly the behavioral context an agent needs.

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

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

Three sentences, front-loaded with the return contents and followed immediately by the usage directive. The first sentence is dense with parenthetical lists but every clause names real payload fields 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 a single required parameter, the description adequately covers what comes back and when to call it. The only gap is the unresolved overlap with the sibling get_influencer, which leaves the selection decision slightly 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 coverage is 100% and the single parameter is documented in the schema as 'Influencer id from list_influencers'. The description adds nothing about the parameter, so baseline 3 applies — the schema carries the parameter semantics entirely.

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+resource and enumerates exactly what the read returns: personality fields, postingTargets, playbook, and draft status counts with pending review cards. It clearly separates itself from decide_influencer_drafts and update_influencer_agent, though it never explicitly distinguishes itself from the sibling get_influencer, so an agent could still hesitate between the two.

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 an explicit ordering directive ('Call this FIRST, before updating settings or deciding drafts'), which implicitly routes the agent away from update_influencer_agent and decide_influencer_drafts. There is no stated when-not-to-use condition, but the sequencing guidance is clear and actionable.

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 safety (readOnly, non-destructive, closed-world). The description adds real behavioral context beyond annotations: it's a polling tool, it returns status/progress, completed state attaches rendered assets as resource links, and the result carries a dashboard viewUrl. It doesn't state any polling interval or terminal error states, but the completion behavior is well disclosed.

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 tightly packed sentences, each earning its place: what it does, what completion yields, and the follow-up sibling. Front-loaded with the action and zero filler.

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

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

For a 2-param polling tool with a full schema and annotations covering safety, the description supplies the lifecycle, completion payload description, and downstream linkage. No output schema exists, and the description conveys the key return concepts (status/progress, asset links, viewUrl), which is sufficient; a bit more on failure/in-progress polling guidance would make it a 5.

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

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

Schema coverage is 100%, and both parameters are documented in the schema (jobId explicitly notes it comes from generate_influencer_snack). The description restates the jobId lineage but adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb+resource (poll a snack pack job) and explicitly ties the lifecycle to the sibling that creates it (generate_influencer_snack) and the sibling that lists the finished result (list_influencer_snacks). An agent can distinguish this from get_snack and get_job 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 names the prerequisite (started by generate_influencer_snack) and the downstream action (list_influencer_snacks will then include the finished pack). The lifecycle sequence makes when-to-use vs. siblings unambiguous.

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

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

Annotations cover the safety profile (readOnly, non-destructive), so the bar is lower. The description still adds genuine behavioral context: it names the polled tool, lists the progress fields returned (status, progressPercent, creditsReserved/credits, error), and gives the completion transition. It does not state a polling interval/frequency, which is a minor 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?

Three tight sentences, front-loaded with the core action, then the return shape, then the next step. No waste; 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 2-param polling tool with annotations covering safety, the description supplies everything needed: the originating tool, the returned progress fields, the error channel, and the completion workflow. No output schema exists, yet the description compensates by enumerating the return fields.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful linkage beyond the schema by tying jobId to 'started by build_influencer_vault' and describing it as a returned build job id, reinforcing the parent-child relationship between the two tools.

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 (poll status), resource (vault build), and names the originating tool build_influencer_vault. An agent can immediately distinguish it from build_influencer_vault or list_influencer_assets.

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 identifies itself as a polling tool for a build started by build_influencer_vault, and routes the agent forward: when status is 'completed', call list_influencer_assets. Clear when-to-use and next-step guidance.

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

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

Annotations already declare readOnly=true and destructive=false, and the description adds valuable runtime behavior: status token variants ('succeeded' in Studio/SeedDance), minimum job duration (≥2 minutes), the exception for TikTok Carousels, and the fact that completed outputs are attached as inline resource links. This is exactly the behavioral context the annotations do not 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?

The description is long but every sentence carries decision-relevant information: scope, coverage, statuses, timing, output links, and exceptions. It front-loads the universal purpose and then packs specifics without filler, earning its 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 universal poller that spans many generation tools, the description tells an agent exactly what to poll, which status strings to expect, how long to wait, and which sibling pollers to use instead. The presence of an output schema makes detailed return-type documentation unnecessary, so nothing needed 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?

The schema already describes jobId as accepting jobId or projectId, so coverage is 100%. The description adds value by enumerating which source calls produce jobIds versus projectId (e.g., AI Edit / Character Swap), helping the agent map the correct id form to the originating call. This enrichment justifies above-baseline scoring.

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-object pair ('Poll ANY async VidGuy job by its id') and immediately labels it 'the universal poller.' It enumerates the covered source tools and explicitly names dedicated siblings for exceptions, so an agent can distinguish it from get_video, get_dub_status, and others without opening their 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?

It states clearly when to use the tool (any async generation) and when not (influencer vault builds / snack packs and dubs have dedicated pollers, named explicitly). It also provides concrete polling cadence guidance (~10s for generations, ~3s for TikTok Carousels) and warns against treating early 'processing' as failure. This is full usage guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, covering the safety profile. The description adds only 'Free' as a behavioral trait; it omits auth requirements, rate limits, and error behavior. The enumerated return fields are output documentation rather than behavioral 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?

One front-loaded sentence; the field list is dense but earns its place because there is no output schema. No filler.

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

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

For a simple read-by-id tool with a fully described parameter and clear annotations, the description supplies the missing return-field inventory and cost note. Nothing essential to invoking it correctly is absent.

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

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

Schema coverage is 100% and the single accountId parameter is already documented as a UUID. The description's 'by id' adds no syntax or format detail beyond the schema. Baseline 3 when the schema does the work.

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

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

States a specific verb and resource: 'Fetch one managed account by id', and it distinguishes itself from list_managed_accounts by scope ('one') and from capacity/pulse siblings through the enumerated return fields. An agent can tell what the tool returns without opening another schema.

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

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

Usage is implied (call when you have an accountId and need its details) and 'Free' adds a cost consideration, but no explicit when-not or named alternative is given. Alternatives like list_managed_accounts or get_managed_accounts_pulse are not mentioned, so selection relies on 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 this is a safe read (readOnlyHint=true, destructiveHint=false), so the bar is lower. The description still adds real value: it discloses the notice-period and warm-up constraints, the 60-day horizon, and the 'free' cost. It omits auth/permission needs and rate limits, so a 4 rather than 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 purpose and efficient overall, but the parenthetical explanations for earliestQueueDate are dense and could be trimmed. Every clause still carries useful information, so minimal 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?

With no output schema, the description correctly takes on the burden of enumerating the returned fields (earliestQueueDate, firstOpenDay, dailyCap, creditsPerPost, countsByDay/fullDays) plus the warm-up/notice semantics needed to interpret them. Nothing an agent needs to call and read the result 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?

Only one parameter (accountId) with 100% schema description coverage, so the schema already does the documenting. The description conveys that the account is a 'hosted / managed' one but adds no format or lookup detail beyond the schema's 'Managed account UUID'. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('Which days a hosted / managed account can take a post') and immediately names what it distinguishes itself from by pointing at publish_to_managed_account. An agent can identify this as a read-only capacity/availability check 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?

Explicitly prescribes the workflow: 'Call this before publish_to_managed_account to pick a legal queueFor day.' The when-to-use and the downstream tool it feeds are both named, leaving nothing 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 cover read-only and non-destructive behavior. The description adds valuable context beyond those: metrics are cached and refreshed about daily, and it exposes the accountsWithMetrics/accountsTotal/capturedAt fields to clarify staleness/coverage 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?

Every sentence earns its place: purpose and scope, metric contents, cache/cost caveat, and the sibling tool alternative. The description is dense but not padded, and the essential differentiating information appears early.

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, but the description compensates by enumerating the returned aggregates, the delta, the time series, and the accounts-with-metrics coverage fields. With a single well-documented parameter and clear response contents, nothing needed to invoke the tool 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?

The input schema already fully documents the days parameter, supported windows, default, and rounding behavior. The description restates the window options but does not add meaning beyond what the schema provides, so the baseline of 3 applies.

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

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

The description opens with 'Roll-up of ALL your hosted / managed accounts' performance' — a specific verb, resource, and scope. It clearly distinguishes the aggregate tool from the per-account 'get_social_analytics' sibling by naming it 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 states the tool is for a roll-up of all managed accounts and explicitly routes the agent to get_social_analytics with source 'managed_account' when a single account breakdown is needed. It also adds cost guidance ('cheap to call', 'Free').

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 annotations indicating readOnlyHint=true, openWorldHint=false, and destructiveHint=false, the safety profile is clear. The description adds valuable behavioral context: it returns a dashboard viewUrl and attaches scene visuals as resource links, and clarifies that these are source clips/images with text overlays and greenscreen applied at render time, directing users to open the viewUrl for the final result.

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

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

The description is two sentences, front-loading the core purpose and then detailing the return behavior. It is reasonably concise, though slightly dense with technical details about resource links and rendering, but every sentence contributes.

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

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

Given there is no output schema, the description provides crucial information about the return value: a viewUrl and resource links for scene visuals, with an explanation of rendering differences. It is nearly complete, though it could mention pagination or error cases, but for a single-item fetch, it covers the 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 coverage is 100%, and the only parameter (snackId) is fully described in the schema as 'Snack post UUID'. The description adds no additional parameter details beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states a specific verb (Fetch) and resource (a single snack post with its manifest) by id. It distinguishes from list_snacks by specifying it fetches one by id, but doesn't explicitly name the sibling alternatives like get_influencer_snack or list_snacks.

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 usage by stating 'by id', which suggests it should be used when you have a snackId. However, there are no explicit when-to-use or when-not-to-use statements, nor any mention of 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 the tool readOnlyHint=true and destructiveHint=false, and the description reinforces the read-only nature. It adds useful behavioral context beyond annotations: 'Free', data-quality flags, previous-period comparisons, and the caveat 'where available' for top posts, which helps set expectations for an open-world result.

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

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

Three sentences with no filler; the core purpose is front-loaded and the content list is dense but efficient. The phrase 'evidence-shaped' is slightly vague, but overall every sentence carries meaningful 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?

There is no output schema, so the description carries the burden of explaining return content. It lists many relevant components, previous-period comparisons, deltas, breakdowns, series, and flags, which gives an agent a solid mental model of the response. It could mention failure modes or unsupported source combinations, but the description is still reasonably complete for a read-only analytics tool.

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

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

Schema coverage is 67%, with days and targetId already described; the source enum values are self-explanatory. The description maps 'connected Social Brand' and 'hosted managed account' to the source parameter, but adds little concrete parameter-level detail beyond what the schema already provides.

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 ('Return') and a well-defined resource: analytics snapshots for either a connected Social Brand or a hosted managed account. The scope is concrete enough to distinguish it from sibling post-listing and account-status tools, even without naming them.

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 when to use it: before making performance claims or content recommendations. It does not spell out when not to use it or name an alternative, so it falls short of a 5, but the provided guidance is clear and actionable.

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

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

Annotations already establish readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds value beyond that: it discloses what data is returned (status, scheduledAt/publishedAt, provider URL once live, error message) and that the call is free — no credit spend. It omits any auth or error-handling behavior, keeping it short of a 5.

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

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

One sentence, front-loaded with the verb and resource, with the return payload and cost note packed into a tight em-dash clause. No filler or redundancy.

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

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

With no output schema, the description carries the return-value burden and does so by naming the key fields an agent would need. Combined with annotations covering safety and the explicit 'Free' cost signal, an agent has enough to call it correctly; only pagination/auth edge cases are unaddressed, which is minor for a single-record fetch.

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

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

Schema coverage is 100% and there is a single parameter (postId, a social post UUID), so the schema fully documents the input. The description adds only 'by id', which conveys no extra syntax or format detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb (Fetch) plus resource (one connected-account post) and narrows scope to lookup by id, which separates it from list_social_posts. It enumerates the returned fields, so the agent knows exactly what it gets. It does not explicitly name the sibling to use for listing, so it falls just short of a 5.

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

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

Usage is implied by 'by id' — the agent infers this is for retrieving a known post rather than discovering posts. There is no explicit when/when-not statement or pointer to list_social_posts for enumeration. The trailing 'Free' hints at a cost consideration but is not framed as guidance.

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

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

Annotations already declare a safe read, and the description adds real behavioral context on top: the four possible statuses, the paid-reservation failure mode with a recovery action, the 24 h signed wordsUrl expiry, and the 15-minute limit on includeWords. This is exactly the operational detail 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 action and status set, then the success payload, then the parameter tradeoffs. Every clause carries unique information; no restatement of the name or 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?

Even though an output schema exists, the description covers the async lifecycle, the failure/payment branch, and the context-budget flags an agent must reason about. Nothing needed to call this 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 coverage is 75% and two flags (includeWords, includeText) carry no schema description, but the description compensates: it explains what each flag does, the 15-minute inlining limit, and that disabling includeText/includeSegments keeps long transcripts out of context. It also clarifies transcriptionId is the jobId from transcribe_media.

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 ('Poll a transcription by its jobId') plus the exact scope of what it returns (status, text, segments, wordsUrl). Clearly distinct from the sibling create-side tool transcribe_media and from list_transcriptions.

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

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

Explains the polling loop well, including the non-obvious payment_required branch and the 'top up creditsDue and poll again' remediation. It never names an alternative tool (e.g. list_transcriptions) or says when not to use it, so it stops 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 cover the safety profile (readOnly, non-destructive), and the description adds real behavioral context beyond them: the output video is surfaced as a resource link when available, and Character Swap projects include replayable settings (r2Keys, keepOriginalVisualRanges, resolution, sceneMatch, saveAudio) plus signed previews. This is meaningful disclosure an annotation 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 return set, then layers the Character Swap special case. Two dense sentences with no wasted filler, though the second sentence is somewhat long.

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 the description appropriately enumerates the return payload (status, outputUrl, brief, per-format asset tiles) and the Character Swap extension. An agent knows what it will get back and how the resource link behaves.

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

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

Schema description coverage is 100% and the single videoId param is already documented as a 'Project UUID from list_videos'. The description restates 'by its id' but adds no format, sourcing, or edge-case detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Fetch one video project by its id') and enumerates what is returned, which distinguishes it cleanly from the sibling list_videos. An agent can tell this is the singular retrieval counterpart to the list operation 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?

Usage is implied (fetch a single project by an id obtained from list_videos, per the schema text), and the Character Swap note hints at a replay workflow, but there is no explicit when-to-use/when-not guidance or comparison against alternatives such as get_job.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is well covered without the description. The description adds useful behavioral context — clones include their consent record — but says nothing about lookup failure behavior or what fields the non-clone case returns.

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, and the retrieval scope leads. It is slightly terse — the second sentence is fragmentary — but every clause carries information 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 one-parameter read tool with annotations carrying the safety profile and no output schema, the description covers the input formats and the notable clone/consent behavior. Adequate for calling it correctly, with only minor gaps around error cases.

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 the single voiceId parameter, so the schema gives the agent nothing beyond the string type. The description compensates by enumerating the three accepted identifier forms (our id, ElevenLabs id, premade alias), which is exactly the meaning the schema is missing.

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 resource and scope: 'One voice' retrieved singularly, which cleanly distinguishes it from the sibling list_voices that returns many. It names the accepted identifier forms (our id, ElevenLabs id, alias) so the agent knows what this fetches, though it never names the sibling it contrasts with explicitly.

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

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

Usage is implied by 'One voice' — fetch a single voice rather than a list — but there is no explicit when-to-use guidance and no alternatives named (e.g., 'use list_voices to browse, use get_voice_consent_statement for consent details'). The agent must infer the boundary from the sibling names.

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, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: this is a consent artifact that must be surfaced to the user and explicitly confirmed before proceeding. It does not, however, discuss caching, versioning semantics, or 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?

Two tightly written sentences with zero filler; the purpose is front-loaded and the required follow-up action closes it. Every clause carries meaning.

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

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

For a no-parameter read with no output schema, the description covers what an agent needs: what is returned (consent text and version) and the mandatory user-confirmation workflow. Nothing essential is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. No parameter guidance is needed or missing.

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 resource (the voice-clone consent text plus its version) and ties it to the related sibling create_voice_clone, so the agent can tell what is being fetched and why. It is clear and non-tautological, though it doesn't spell out the exact return shape beyond 'the consent text... with its version'.

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 names the trigger condition ('before create_voice_clone') and instructs the agent what to do with the result ('Show it to the user and get their explicit confirmation first'). This is precise when-to-use guidance tied to a concrete workflow step.

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