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

Annotations already disclose that this is a non-read-only, open-world, non-idempotent but non-destructive operation. The description adds substantial behavioral context beyond annotations: no source video is cut or re-rendered, accepted inputs include files, URLs, platform pages, and social post links, no-speech cases are refunded, and work runs in the background and lands in the Library.

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 front-loaded, starting with the core action and output before moving into mode-specific details. Every sentence carries useful operational information, with no filler or repetition.

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

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

For a six-parameter tool with no output schema, the description covers the essential behavior: outputs, styling defaults, cue mode, source types, refund behavior, and background/Library handling. It does not fully explain the asynchronous job result shape or how to retrieve the finished output, which keeps it short of 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 description coverage is 100%, so parameter syntax is already well documented. The description still adds meaningful semantics by explaining default textStyle behavior, when to set textStyle, the distinction between sentence timing and auto:'words', how cues override transcription, and that burn:false returns only the .srt.

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: burn subtitles into a video and also get the .srt. It distinguishes the operation from sibling video tools by emphasizing that nothing is cut or re-rendered and by describing subtitles as the output rather than a general edit.

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 clear conditional guidance for the main modes: set textStyle only when the user describes a look, use auto:'words' for phrase-level timing, pass cues for exact untranscribed lines, and use burn:false for only the .srt. It does not explicitly compare this tool with sibling alternatives such as edit_video or dub_video, but the internal usage guidance 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 already declare openWorldHint=true, idempotentHint=false and destructiveHint=false, and the description's '~A transcription call.' hints that this is a compute/credit-bearing operation rather than a pure metadata read — relevant given readOnlyHint=false. But it does not explain the cost, latency, or async/non-idempotent behavior that the annotations imply.

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?

Very compact and front-loaded, leading with the returned structure and closing with the use case. It is telegraphic and sentence-fragmentary, which slightly hurts readability, but every clause earns its place.

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

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

There is no output schema, and the description compensates by enumerating what is returned (transcript, beat list, duration, frame times). Combined with four annotated parameters and a required url, an agent has enough to invoke it correctly; only cost/async behavior remains undisclosed.

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

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

Schema description coverage is 100%, so all four parameters (url, words, frames, anchors) are already documented in the schema. The description alludes to two of them ('transcript' for words, 'sampled frame times' for frames) but adds no syntax or format details beyond the schema. Baseline 3 is appropriate when the schema carries the parameter burden.

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 (analyze) and the exact artifact produced: verbatim transcript, beat list, duration and sampled frame times for a video ad. That is well beyond restating the title. Sibling differentiation is only implicit, via the phrase 'before remixing it', rather than naming a concrete alternative.

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?

'study a reference before remixing it' gives a clear triggering context for the tool and ties it to the remix/clone family (clone_video, remix_static, etc.). It stops short of stating when not to use it or naming a specific alternative tool, so it is context without exclusions.

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

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

Annotations cover mutation semantics (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false). The description adds value by disclosing that the dropdown chip is 'confirmed by reading the doc back' — an irregular verification step an agent would not otherwise expect. It does not describe failure modes, rate limits, or permissions, keeping this at a 4.

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 front-loads the core action and then details the dropdown nuance and confirmation step. It is a single tight paragraph, but the parenthetical about the dropdown example is fairly dense and could be split for readability. No wasted marketing language.

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 annotations, full schema coverage, and no output schema, the description covers what an agent needs: the action, how to obtain documentId, the dropdown behavior including its confirmation, and a pointer to update_doc for later changes. It stops short of covering edge cases like doc permissions failures, which is acceptable given the annotation set.

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

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

Schema coverage is 100%, so the schema carries parameter documentation and the baseline is 3. The description goes beyond by explaining the combined use case of `text` and `dropdown` (e.g., 'Status: ' prefix followed by a status chip), and by clarifying that appending a dropdown benefits from later update via update_doc dropdowns.

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 (append) and resource (text to end of a Google Doc) and clarifies the two reachability paths: docs it created via create_doc's documentId, or user-picked docs found with list_drive_files. This distinguishes it from read_doc and update_doc in the sibling list.

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?

Description explains when to use append (adding text at the end) and how to obtain documentId for both ownership cases, and points to update_doc dropdowns for later correction. It does not explicitly rule out in-place edits or explain when to prefer append over update_doc, but the context is strong enough for an agent to route correctly.

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

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

Annotations already declare destructiveHint=false and openWorldHint=true. The description reinforces these with 'Nothing already on the page changes' and adds the cost signal ('Free'), which are useful beyond the annotations. Return behavior isn't described, but with no output schema that omission is minor.

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 action, then the modes, then the non-destructiveness and cost. Dense with zero 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 4-param write tool with a fully covered schema and clear annotations, the description conveys scope, non-destructiveness, source of pageId, and cost. It doesn't describe the response, but with no output schema that's an acceptable 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%, so the baseline is 3. The description adds real value by indicating pageId's source ('from list_notion_pages') and framing the three optional modes; the swipefile detail largely restates the schema, so it doesn't rise to a 5.

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

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

States a specific verb (Add/append), resource (existing Notion page), and scope (to the END). The 'Nothing already on the page changes' clause distinguishes it from a save/overwrite operation like save_to_notion, and the three append modes are enumerated.

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?

Tells the agent where pageId comes from (from list_notion_pages) and what can be appended (markdown, swipefileCollection, includeSchedule). Clear usage context, but it doesn't explicitly name alternatives like save_to_notion or state when not to use it.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, and idempotentHint=false. The description adds useful access constraints and id-discovery paths, but it does not describe append semantics such as where rows land or what happens on repeat calls.

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 compact and front-loads the core action before adding access and id-source guidance. The sentence is dense but every clause supports correct invocation.

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 append mutation, the description covers reachability, spreadsheetId sourcing, and row shape while annotations cover safety and schema covers parameters. It does not explain return behavior, but no output schema exists and this is a minor omission.

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 all three parameters are already documented. The description reinforces rows as an array of row arrays and clarifies that spreadsheetId can come from create_sheet or list_drive_files, but it omits the optional range 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?

The description states a specific verb and resource: appending rows to a Google Sheet. It also clarifies reachable-sheet scope, though it does not explicitly distinguish append behavior from update_sheet or other sheet-writing 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?

It gives clear usage context: the sheet must be one Hermoso created or one the user handed over via the Google file picker, and it names create_sheet and list_drive_files as sources for spreadsheetId. It lacks explicit when-not guidance against update_sheet or clear_sheet_range.

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

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

Beyond the annotations (readOnlyHint false, idempotent, openWorld, non-destructive), the description discloses the DRY-RUN default, that a cost quote is returned, that runs are bounded and resumable via a cursor, and that the operation is free. It also explains the downstream data-model consequence — imported posts are labelled 'backfilled', weaker evidence, and stay UNATTRIBUTED unless matched by asset or caption. That is exactly the behavioral context annotations cannot carry.

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

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

Front-loaded with purpose and a bolded 'BOUNDED, RESUMABLE AND QUOTED' section, then caveats. Dense rather than padded, though the long parenthetical cataloguing LinkedIn, X, Google and Telegram costs some length for information that only matters if an agent tries an unsupported channel.

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

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

For a mutation tool with no output schema, the description covers the essentials an agent needs to call it safely: default safe mode, the confirm gate, pagination/resume path, which channels work, and what the imported data means downstream. Remaining details (return shape beyond counts and cost) are adequately implied by the quote step.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning on top: confirm:true is the switch from quote to import, and the cursor is described as coming back from a prior run and being passed in to continue — a usage pattern the schema only hints at. The limit and accountRef parameters are left entirely to 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 states a specific verb and resource — importing a brand's past posts from a named channel into the performance record — and frames the outcome ('so which hook works can draw on history'). It implicitly contrasts with recorded posts but never names a sibling tool such as list_published_posts, so differentiation is by concept rather than by routing.

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-to-use is clear (to give hook analysis historical depth) and when-not is unusually thorough: each unsupported channel is listed with the concrete reason (LinkedIn grant, X per-read billing, Google Business insights discontinued, Telegram Bot API limits). It also states the dry-run default and confirm:true to actually import. What's missing is explicit direction to an alternative tool for viewing already-recorded posts.

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 read-only, idempotent, and non-destructive behavior, but the description adds substantial context beyond them: billing permission visibility, member-scope limitations, the risk of falsely telling a member no card is on file, and how memberRate, legacy plans, and posting allowances should be interpreted. This is exactly the kind of behavioral caveat an agent needs for a billing-status 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 front-loaded with the purpose and permission-critical caveats, and every clause carries meaning. It is dense and long, with multiple parenthetical clarifications, but the length is justified by the breadth of billing states and the member-scope warning.

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

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

With no input schema and no output schema, the description must explain what the tool returns and what the agent should infer from it, and it does so thoroughly. It covers plan pricing interpretation, credit balance, auto-reload/card visibility, admin rights, and posting allowances, which is complete for this read-only status 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?

There are zero input parameters, so the baseline is 4; no parameter semantics are needed. The description instead spends its space clarifying return semantics, which is useful but does not change the input-parameter score.

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?

It names the specific resource (this account's billing) and enumerates the exact fields returned: plan, credit balance, auto-reload, card on file, and admin rights. This clearly distinguishes it from sibling tools like upgrade_plan, set_auto_reload, and buy_credits.

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 explicitly says to call it before upgrade_plan or set_auto_reload to know what is possible, and explains that members have read-only billing. The shared-workspace member limitation is called out with concrete guidance on what to say and not say.

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 that the charge is instant with no redirect, that the card is persisted for one-click after the first purchase, that quote_token has a 10-minute validity window, and that money is actually moved. The note that a same-token retry is idempotent is a refinement of idempotentHint:false rather than a contradiction — fresh quotes can still double-charge.

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 and logically ordered through the three paths, but the long all-caps paragraph about POSTing to /api/billing/machine-payment describes a raw HTTP lane this tool cannot invoke, so it is largely unusable noise inside a tool description. The core flow could be stated in half the 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?

With no output schema, the description compensates by describing what comes back on each path — the pack list (id · credits · price), the quoted charge amount, or a checkout URL. Combined with the annotations and the fully described schema, an agent has everything needed to call correctly.

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

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

Schema coverage is 100%, so the individual fields are already documented; the description earns extra credit by explaining the two-step sequencing (quote → confirm with the binding token) that the flat schema cannot express. It does not, however, add format or validation detail beyond the schema.

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

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

States a specific verb and resource — topping up credit packs — and explicitly bounds the scope ('Packs only; subscriptions are managed by a person in Billing'), which separates it from upgrade_plan and set_auto_reload. An agent knows exactly what this tool transacts and what it does not.

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 a complete decision tree: no argument lists packs, `pack` alone quotes, `pack` + confirm + quote_token charges, and a missing saved card falls back to a Stripe checkout URL. It also names the prerequisites (saved card, billing-admin rights) and points to set_auto_reload as the preventive alternative.

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

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

Beyond the annotations, the description discloses that invoking through call_tool uses the same permissions, account, and result as a direct call; that arguments are validated against the target tool's schema; that invalid arguments return the expected parameters rather than silently defaulting; and that tools requiring unavailable connectors or withheld by host policy are refused by name with an actionable way out. This is rich, non-obvious behavioral context.

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, source of parameter values, host-specific rationale, validation behavior, and refusal conditions. The most important action and scope are front-loaded, and the length is justified by the complexity and risk of a generic tool dispatcher.

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 as a dynamic dispatcher and the absence of an output schema, the description fully covers how to invoke it, how to source parameters, what validation behavior to expect, and when/why it may refuse. The statement that results match a direct call also informs the agent about return behavior without needing an 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?

Schema coverage is 100%, so the baseline is 3. The description adds operational meaning by directing the agent to obtain the exact name and args from find_tools and by explaining that args must match the target tool's own schema, with validation errors surfacing expected parameters. This goes slightly beyond the schema's bare definitions.

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 specific verb and resource: 'Run ANY Hermoso tool by name', and immediately clarifies its unique scope—it can invoke tools not in the session's starting list, including paid-campaign, analytics, and channel-admin tools. This clearly distinguishes it from the many specific sibling tools and from enable_tools.

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 explicit when-to-use guidance: it is the route on hosts like claude.ai and ChatGPT that cannot reload their tool list mid-conversation. It also names the alternative (enable_tools) and explains why that alternative fails on such hosts, plus instructs the agent to get the exact name and args from find_tools first.

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 safety and idempotency are covered. The description adds genuinely new behavioral context: the operation is state-dependent and silently inapplicable once a post has published. It stops short of describing auth/brand requirements, but the added constraint is meaningful.

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 action, then the id source, then the state constraint and alternative. No sentence is filler.

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

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

For a destructive mutation with no output schema, the definition covers action, prerequisite lookup, state constraint, and the fallback tool. Combined with annotations that carry the safety profile, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100% and both parameters are fully documented in the schema, including the 'brand' profile-matching rule. The description only reinforces where 'id' comes from, adding nothing 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?

The description states a specific verb and resource — 'Remove a queued post before it goes out' — and clearly distinguishes this from siblings like reschedule_post, retry_scheduled, and duplicate_scheduled, which act on the same scheduled-post resource but do not remove 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?

It gives explicit preconditions ('Only works while it is still queued'), a clear when-not ('something already published cannot be unsent'), and names the alternative for that case ('use manage_meta_post to delete a Facebook/Instagram post after the fact'). It also routes the agent to list_scheduled to obtain the id.

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

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

Annotations declare it is not read-only, open-world, not idempotent, and not destructive. The description adds behavior beyond annotations: it preserves performance, lip-sync, and background sound, notes it is paid, and says it returns the served URL. It does not mention permission or billing amount details, but the added context is meaningful.

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 with zero waste. The main operation and preservation behavior are front-loaded, followed by routing guidance and a brief return 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?

With no output schema, the description explains the return value as the served URL. It also covers preservation behavior and cost status. Missing details such as credit amount or processing time are minor for a tool whose annotations and schema are otherwise 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 100%, and the schema already documents both parameters thoroughly, including default voice behavior and voice-clone naming. The description adds no further syntax or format detail beyond what the schema provides, so baseline 3 applies.

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

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

The description states a specific verb and resource: swapping narration of a finished video into a different voice. It also distinguishes the operation from sibling dub_video, which is reserved for translation.

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 usage conditions: 'Use when the user likes the video but wants a different narrator voice' and directs language translation to dub_video. No inference is needed to choose between them.

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?

Discloses behavior the annotations don't: a flat 1-credit cost, that it pulls Meta's live policy pages, the exact return shape (pass/fix/block verdict with verbatim policy quotes and a compliant rewrite), and that it is non-mutating for the creative. This is rich context beyond the readOnlyHint/openWorldHint flags and compensates for the absent 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-loads the core purpose and the cost, then layers in return behavior and use cases. Every sentence earns its place, though the emphasis-heavy single paragraph (caps, em-dashes) is slightly longer than needed.

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?

Despite having no output schema and four parameters, the description covers cost, data source, return verdict, and non-mutation behavior, plus which inputs matter most. An agent has everything needed to decide to call it and to call it correctly.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema, warranting the baseline 3. The description adds only marginal semantic help by implying the category parameter should map to regulated-adjacent verticals; it adds no format or value guidance beyond the schema.

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

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

States a specific verb+resource ('Pre-flight ad copy against Meta's REAL, live Advertising Standards') and the exact deliverable (a pass/fix/block verdict). It clearly distinguishes itself from sibling generation/analysis tools by framing itself as a pre-publication policy gate and a 'check, not an edit.'

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 strong when-to-use guidance: run it before you publish, and especially for regulated-adjacent categories and absolute/guaranteed claims. It also draws a clear functional boundary ('it never changes the creative'). It stops short of naming a competing sibling (e.g., score_ad, plan_ad) or stating when not to use it, so it lacks the explicit alternatives of a 5.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds substantial context beyond them: a two-phase dry-run/confirm flow, the fact that no default range exists, that the clear is read back and only reported confirmed if the range is genuinely empty, and the rationale for the count echo as a guard against mis-typed ranges. This is exactly the additive behavioral disclosure the lower bar asks for.

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 critical information — destructive two-phase confirm flow — is front-loaded and the sentences are largely purposeful. It is slightly padded by editorial lines ('The echo is not ceremony: it is what catches naming A1:Z1000...'), which are persuasive but not strictly operational, keeping it short of a 5.

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

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

For a destructive, no-output-schema tool, the description supplies the safety flow, the expected return of the unconfirmed call (filled-cell count), the confirmation semantics, and the alternative for tab removal. An agent has everything needed to invoke it correctly and safely; no material gap remains.

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 100% schema description coverage the baseline is 3, and the description adds real meaning on top: it explains the two-step interaction between confirm and confirmCells (the count must be echoed back from the first call). It does not separately explain sheetUrl vs spreadsheetId, but the schema covers those adequately, so this is a modest value-add rather than a full parameter walkthrough.

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 ('Empty a range of cells in a Google Sheet') plus a key scope constraint ('leaving the rows themselves in place') that separates it from tab deletion. It explicitly routes the remove-a-whole-tab case to manage_sheet_tabs, so an agent can distinguish it from that sibling without opening either schema.

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

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

The description gives a complete call sequence: first call without confirm to obtain the filled-cell count, show it to the user, get an unambiguous yes, then call again with confirm:true and confirmCells. It also names the alternative (manage_sheet_tabs) for a whole-tab removal. Nothing is left to inference about when and how to use it.

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 annotations, it discloses meaningful behavior: it reads the page, saves the product to the brand catalog, pins the real product photo to this ad without changing the brand's default, falls back to a real browser and then to link/search data, and says the reply notes that fallback. This adds substantial context that annotations alone (readOnlyHint=false, destructiveHint=false, openWorldHint=true) 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 core action is front-loaded in the first sentence, followed by side effects and the render_ad handoff. It is somewhat dense with run-on clauses, but nearly every sentence carries useful behavioral detail 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?

For an open-world mutation tool with no output schema, the description covers side effects (catalog save, photo pinning), fallback behavior for hidden pages, and the required next step of calling render_ad. It does not describe the shape of the returned creative, but it does enough to let an agent use 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 description coverage is 100%, so the schema already documents url, say, style, language, and durationSeconds, including the style enum. The description reinforces the url concept but does not add meaning to the other parameters, 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 states a specific verb and resource: paste a product page link and get a creator-style video ad planned for that product. It distinguishes itself from siblings by explicitly saying 'Nothing renders here' and routing rendering to render_ad, so an agent can tell it apart from generate_video or render_ad 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 gives clear usage context (paste a product link, works with or without a saved brand) and a concrete next step: show the concept, then call render_ad with the returned creative, using dryRun:true first for the exact price. It does not name alternatives such as plan_ad or product_sizzle, so the routing is strong on the follow-up but incomplete on sibling selection.

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

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

Annotations only say readOnly=false/openWorld/idempotent=false/destructive=false. The description adds real behavioral context the annotations cannot: the ~7-credit hold settled to actual cost plus a separate vision-call event, fast/cheap because no video model renders, only first ~40 min analysed with a truncated flag, failed/unsupported inputs 'fail fast... and are fully refunded', and captions burned in by default. That is exceptional depth beyond the structured hints.

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

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

Extremely information-dense and mostly front-loaded, but the wall of CAPS-emphasised clauses, parenthetical engine lists, and refund/truncation/caption caveats make it hard to scan; several sentences are doing three jobs at once. Some of this could be trimmed without losing the substance, so it lands at adequate-but-overstuffed.

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?

A no-output-schema mutation-ish tool that nonetheless explains inputs accepted/rejected, cost model and refund behavior, truncation, reframe logic (subject-aware single-offset crop, centre fallback, reframedToSubject/reframeWhy fields), captions default, and return shape (clips[] with URL/title/hook/caption/score/timecode). 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 description coverage is 100%, so the baseline is 3. The description still adds real value: it explains the default and rationale for captions:false, notes the SUBTITLES default in prose, and mentions captionsBurned/captionNote outcomes tied to the captions parameter. It adds meaning beyond the schema rather than repeating it, warranting a 4.

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 ('cut ONE long video into several RANKED, ready-to-post short clips') and resource, and the parenthetical domain list (podcast/webinar/interview/talk/ad -> Reels/Shorts/TikTok) pins the exact use case. A reader can distinguish it from reframe_video, edit_video, and stitch_video 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 accept/reject conditions ('YouTube link... or direct https .mp4', 'NOT supported: TikTok / Instagram / Facebook links, and anything age-restricted, private...'), including the correct fallback ('ask for a direct file or an upload rather than retrying'). It does not name sibling alternatives (e.g. reframe_video for an existing short, edit_video) as when-to-use forks, so it stops just 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 declare non-read-only, non-idempotent, open-world behavior, and the description adds genuinely useful context beyond them: billing cost ('Bills as one image generation'), a side effect ('switches this key's active profile like use_brand'), and the guarantee that source branding is removed. It does not describe failure modes or output format, but the added billing and side-effect disclosure is strong.

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?

Core purpose is front-loaded in the first clause and alternatives follow. It is somewhat dense with capitalized emphasis and a long trailing billing sentence, but nearly every sentence carries distinct information (scope, parameter, alternative, billing).

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

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

With no output schema, the description still conveys what is produced (on-brand static ad, source branding removed), the billing model, the profile side effect, and the sibling alternative. 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 coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema: it clarifies imageUrl is the static ad image to clone and that brandId has the side effect of switching the active profile like use_brand — information not present in the parameter 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 specific verb and resource ('STATIC-AD CLONE ... rebuild a competitor/reference STATIC (image) ad as an on-brand version') and explicitly distinguishes itself from clone_video. An agent can identify exactly what this produces (an on-brand static ad) and what it is not.

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 ('for a static image ad'), when-not ('IMAGES ONLY — for a video ad use clone_video with its link, then render_ad'), and how to target a specific brand profile. Alternatives are named with the condition that selects them.

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 only declaring readOnlyHint=false and openWorldHint=true, the description carries real weight: it discloses that Hermoso WATCHES the clip (frames, transcript, cut map), states the cost (~2 credits), warns that YouTube sometimes refuses server fetches and the plan then rests on captions/thumbnail only, and caps length at 60s. This is unusually rich behavioral disclosure; the only thing missing is any error/failure mode beyond the YouTube case.

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, front-loaded with the core action and brand-scoping, then moves to behavior, cost, and edge cases. Every sentence does work, but the run-on middle section (watching behavior + storyboard rules) could be split for faster scanning.

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 compensates by describing the reply ("says exactly what was watched") and the degraded-caption case. Combined with the cost note and the render_ad handoff, an agent has everything needed to call this and act on the result.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: the 60-second cap and the default of matching the original's length unless durationSeconds is given, plus the brand-omission fallback. That is genuine added value over the structured fields.

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?

"Remake a video you like FOR THIS BRAND from its link" gives a specific verb (clone/remake) and resource (a source video), with an explicit scope qualifier (for this brand). It is immediately distinguishable from siblings like dub_video, clip_video, reframe_video and analyze_video, which are never named but clearly occupy different verbs.

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

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

It routes the agent explicitly: renders nothing, so pass the returned creative to render_ad; for a local file, use upload_file first; omit brand to fall back to get_brand's saved brand. These are concrete when-to-use and what-to-do-next instructions with named 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?

Discloses behaviors well beyond the annotations: absence is recorded as ABSENT with a reason rather than zero, failed reads become 'could not tell' and contribute nothing, and the metered-X skip is always reported so a missing channel isn't misread as poor performance. The write-to-time-series nature is also stated, which is consistent with readOnlyHint=false and idempotentHint=true.

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 layers the accrual model, absent/failed handling, and the metered-X caveat in a logical order with no filler sentences. It is on the longer side with heavy capitalization emphasis, which is slightly dense but each sentence carries distinct 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 still explains what happens to results (stored as a time-series), how missing data is represented, and how skips are surfaced. Nothing an agent needs to invoke this correctly or interpret its effects is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value by explaining the credit cost of includeMetered and the user-notification requirement, which the schema only partially covers. It does not add much for 'max' or 'brand' beyond the schema text, keeping it from a 5.

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

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

States a specific verb and resource ('Fetch fresh performance numbers for this brand's recorded posts and store them as a time-series'), and the accrual/skip behavior makes it clearly distinct from a plain metrics reader like post_performance. An agent can tell what it does and how it differs 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 context for use: readings are due at ~24h and ~7d, only due readings are collected, and X is skipped unless includeMetered:true is passed (with an instruction to tell the user about credits first). It stops short of explicitly naming a sibling alternative for the 'just show me the numbers' case, so it is strong context without full when-not 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 only declare readOnlyHint=false and openWorldHint=true; the description goes far beyond by disclosing the credit cost model ('Spends credits', 'free when you pass ads') and that the auto-pull consumes the same ad-library reads as search_meta_ads. It also discloses the personalization behavior (auto-tailors white space and counter-plays to the saved brand), which materially affects output.

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 deliverable list before the operational contract, and every clause carries information (outputs, input contract, cost, personalization). It is a single dense paragraph with heavy ALL-CAPS emphasis, which aids scanning but makes it slightly harder to parse than a two- or three-sentence layout.

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

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

With no output schema, the description compensates by enumerating the report sections the agent should expect back. For a 3-parameter tool with one nested object, the paid-vs-free branch, data provenance, and per-brand personalization are all covered — 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?

Schema coverage is 100%, so the baseline is 3, but the description adds non-obvious semantics: that the `ads` array must be raw objects from a prior call and that its absence triggers a paid auto-pull, plus that longest-running ads are treated as proven winners. The `domain` sharpening hint is already in the schema, so the gain is real but partial.

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 ('Tear a competitor's ad strategy down') and enumerates the concrete deliverables (hook mix, longest-running themes, white space, counter-plays, avoid-list). This clearly separates it from sibling ad-search tools like search_meta_ads and pull_competitor_ads, which only retrieve ads rather than produce a playbook.

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 CONTRACT sentence states the branch condition explicitly: supply `ads` to analyze exactly those, or omit it to auto-pull. It also names the sibling tools that produce compatible input (pull_competitor_ads / search_meta_ads), so the agent knows both when to use this and where upstream data comes from.

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, open-world, idempotent write, but the description adds substantive behavior they cannot convey: the key is validated live with the provider before anything is persisted, nothing is saved on failure, the reply is read back from the saved connection, and Hermoso never echoes a submitted key. It also documents the non-obvious Apple Ads branch where a signing key pair and setupToken are generated first.

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

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

Well front-loaded — purpose first, then the security/alternative guidance, then field specs. But the body is a single run-on paragraph with the provider roster enumerated twice (display names in prose, ids in the field list), and the key-handling warning interleaved with setup instructions; bullets or a short structured layout would read faster without losing content.

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, yet the description explains what comes back (the saved connection read back from the provider) and the Apple Ads setupToken round-trip. For a mutating, open-world tool with nested parameters, an agent has everything needed to call it correctly and to explain the privacy consequence to a user.

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

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

Schema coverage is 100%, but the schema's 'fields' object is generic (string→string), so the per-provider field lists with '*' required markers add real meaning that the schema cannot express. Small gap: the display names in the prose (AppLovin Ads, ChatGPT Ads, Bing Webmaster Tools) are only implicitly mapped to their ids (applovin_ads, openai_ads, bing_webmaster) via the later field dump.

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 ('Connect an account that links with a KEY rather than a sign-in screen') and enumerates the exact provider set covered. It also draws the boundary that matters most: OAuth-based accounts 'cannot be connected here', which the agent cannot infer from the name alone.

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

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

Gives explicit routing instructions: 'OFFER BOTH WAYS AND LET THE USER CHOOSE', naming the in-app alternative (Workspace > Connectors, or the one-click link) and the privacy tradeoff that selects it. It also states the when-not case (OAuth providers) and prescribes the fallback — answering with the sign-in link to hand the user.

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: conversion happens on Microsoft's servers with no local re-encoding, JPG requires both width and height or Microsoft rejects the call, and the returned URL is durable while Microsoft's own link expires in minutes. This is exactly the operational detail an agent needs and cannot get from readOnlyHint/destructiveHint alone; nothing contradicts the annotations.

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

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

Front-loads the core action and the JPG constraint is capitalized and easy to spot. Some enumeration of formats and ad-copy flourishes ('hand someone a PDF of a spreadsheet') run long, but they carry real capability information 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 correctly fills the gap by describing the return value (a durable Hermoso URL usable in a render or post) and warns against the expiring Microsoft link. Prerequisites, the conditional parameter rule, and format support are all covered.

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

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

Schema coverage is 100%, so baseline is 3; the description goes one step further by explaining *why* width and height matter (Microsoft refuses the call without both), which reinforces the hard conditional requirement rather than merely restating it. It says little extra about fileId or the format default beyond the schema.

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

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

States a specific verb and resource (turn a OneDrive file into PDF or JPG) and immediately scopes it to files already in OneDrive, which distinguishes it from upload/import siblings like save_to_onedrive and get_onedrive_file. The list of supported source formats makes the tool's capability 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?

Gives concrete when-to-use scenarios (client deck to ad images, PSD/raw to JPG, spreadsheet to PDF) and names the prerequisite (OneDrive connected, no new permission). The 'nothing else in this product can open' framing implicitly routes raw/PSD/AI cases here rather than to generate_image or edit_image.

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 (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds real behavioral context beyond them: profile-level isolation ('nothing leaks between them'), the dedupe rule that re-running with the same name returns the existing profile, and the fact that creation is free while a following draft costs credits and refuses before charging.

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 alternatives, and the idempotency and cost notes are valuable. It slips slightly: the long inventory of profile-scoped resources (memory, swipefile, Library, avatars, skills, playbooks, connectors) is expendable, and the credit/refusal logic for draft_brand is fairly verbose for a create 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, so the description carries the return semantics and does so adequately (returns the existing profile when the name repeats). With safety annotations present, the description fully covers what an agent needs: purpose, alternatives, isolation, idempotency, and cost prerequisites.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning to both parameters: 'switch to it' clarifies that activate defaults to making the new profile the active scope, and the name-based dedupe semantics change how 'name' behaves on repeats (returns an existing profile rather than erroring or duplicating).

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 ('Add a NEW profile') and enumerates what counts as a profile (brand, client, creator, personal workspace), which no sibling tool does. It explicitly distinguishes itself from draft_brand and update_brand, so an agent can pick it without opening any schema.

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

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

Gives explicit when-to-use routing: use draft_brand to FILL the profile and update_brand to EDIT it, with this tool only creating. It also states the prerequisite (credits for the subsequent draft, ~100) and the failure mode when the requirement is unmet, which is the kind of guidance agents need before invoking.

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 carry the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower. The description adds value beyond annotations by disclosing the auth/connection requirement (Settings > Connectors > Google Drive, one connection covers all three) and the return payload (document id + URL), neither of which the annotations provide. No contradiction with the write-creating-new 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?

Three sentences, no filler. The core action and scope are front-loaded in sentence one, the return value in sentence two, and the prerequisite in sentence three. Every sentence earns its place, and the example list is compact but illustrative.

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-parameter creation tool with full schema coverage and annotations covering the safety profile, nothing an agent needs is missing: inputs are schema-documented, the return value is stated (important since there is no output schema), the auth prerequisite is explicit, and non-idempotency is covered by annotations. The description is fully self-sufficient for correct invocation.

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

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

Schema description coverage is 100% — both `text` ('body text to insert') and `title` ('document title') are already documented, so the baseline is 3. The description adds only marginal value: the word 'optional' in 'optional body text' (consistent with 0 required params) and content-type examples for the body. It doesn't go beyond the schema in any substantive way.

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 ('Create'), resource ('a new Google Doc in the user's Drive'), and inputs ('title + optional body text'), with concrete content examples (ad copy, creative brief, report). The qualifier 'new' plus the stated return of 'document id + URL' clearly distinguishes it from the doc-modification siblings (append_to_doc, update_doc, read_doc) without needing to inspect those 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?

The description implies usage through content-type examples and states an explicit prerequisite ('Needs Google Drive connected...'). However, it never names alternatives or exclusion conditions — e.g., it doesn't say 'use append_to_doc for existing docs' or 'use create_sheet for spreadsheets' — leaving the actual selection rule ambiguous given the large sibling list.

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

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

Annotations already signal non-read-only and non-idempotent behavior, and the description adds the return format (folder id + webViewLink) plus how the ID flows to sibling tools. It also clarifies the find-or-create behavior of save_to_drive, which is useful context beyond the structured annotations. 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 sentences, each with distinct value: purpose, return value and downstream usage, and a cross-tool caveat. No filler and the core action is front-loaded. It is appropriately sized for the tool's complexity.

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

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

For a two-parameter create tool with no output schema, the description covers the return value, nesting behavior, and downstream consumption examples. It also addresses the confusing relationship with save_to_drive, making the tool effectively self-contained. An agent can call this correctly without additional clarification.

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% with both name and parentId documented, so the schema carries the basic meaning. The description goes further by explaining that parentId creates a nested folder (defaulting to root) and that the returned ID is used downstream. This adds practical parameter usage that the schema alone does not provide.

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 'Create a folder in the user's Google Drive' — a specific verb and resource — and clarifies it can be nested under parentId. It clearly distinguishes itself from related tools like save_to_drive and update_drive_file by explaining the folder creation role. Unambiguous and immediately actionable.

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 explicitly tells the agent to use the returned ID as update_drive_file's moveToFolderId or as parentId for a nested folder. It also warns that save_to_drive's folder parameter takes a NAME, not this ID, steering the agent away from a common misuse. This provides direct alternative routing and practical 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 establish that this is not read-only and not destructive. The description adds useful behavioral context by stating the return value includes folder id + webViewLink, which is beyond the annotations. It could mention idempotency implications or duplicate-name behavior, but the essential side effect is clear.

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 compact sentences, each earning its place: the first explains the action, the second explains how to consume the result, and the third clarifies a critical distinction from save_to_onedrive. 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?

The tool is simple, with only two well-documented parameters and no output schema. The description supplies the missing return-format information (folder id + webViewLink) and how to use it in dependent tools, making the definition fully actionable.

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 name and parentId are already documented. The description adds 'optionally nested under parentId' and mentions the root default, but this is largely restating what the schema already provides. It does not add significant new parameter meaning beyond the structured 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 uses a specific verb and resource: 'Create a folder in the user's OneDrive'. It immediately distinguishes this from Google Drive siblings by naming OneDrive, and it includes the optional parentId nesting behavior. The tool's role is unambiguous.

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

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

The description explicitly explains how to use the returned folder id — as update_onedrive_file's moveToFolderId or as parentId for a nested folder. It also warns that save_to_onedrive's `folder` parameter expects a NAME, not this id, which prevents a likely misuse and distinguishes this tool from a related sibling.

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?

The annotations already declare that this is a non-read-only, non-idempotent, open-world creation tool. The description adds useful context beyond that: it returns the spreadsheet id and URL, rows can optionally be filled, and Google Drive must be connected. It still does not cover failure modes such as duplicate titles or permission errors.

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

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

The description is front-loaded with the core action, then efficiently covers row formatting, return values, and the connection prerequisite. Every sentence adds practical value 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 simple two-parameter creation tool with annotations and no output schema, the description is complete: it explains the output, optional row filling, and the required Google Drive connection. An agent has enough information 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 description coverage is 100%, so both parameters are already documented. The description repeats the rows format and header convention without adding meaningful semantics beyond the schema, so the 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 states a specific verb and resource: create a new Google Spreadsheet in the user’s Drive. It is clear what the tool does, but it does not explicitly differentiate itself from related siblings such as create_doc, save_to_drive, or append_to_sheet.

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 examples — exporting a swipefile, ad list, or performance report — imply when the tool is useful, and the Google Drive connection prerequisite is stated. However, it does not explicitly say when to use this instead of append_to_sheet, update_sheet, create_doc, or save_to_drive.

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 destructiveHint=true; the description adds the far more useful context of what is destroyed, that it is irreversible, that it affects everyone the workspace is shared with, that reconnecting accounts requires a browser no agent can do, and that a first-call inventory must be shown verbatim before confirming. This is well beyond what the structured annotations 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?

The destructive scope is front-loaded in the first clause and every subsequent sentence carries operational weight (the inventory step, the confirmation guards, the anchor-profile exception). It is dense and long, but the length is justified by the irreversibility of the operation; only minor tightening is possible.

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 tool with no output schema, the description covers the return of the first (inventory) call, the required arguments for the second call, the shared-workspace consequences, and the one case where the tool will not work. An agent has everything needed to call it correctly and safely.

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

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

Schema coverage is 100% and the schema descriptions already explain confirm, confirmName, and confirmConnectors, so the baseline is 3. The description adds real value beyond the schema by explaining WHY the name/count guards exist ('confirming INTENT does not prove you picked the right WORKSPACE'), plus the sequencing of when each becomes required.

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 (permanently delete), a specific resource (profile), and enumerates the blast radius (brand details, memory, swipefile, Library, assets, avatars, skills, playbooks, chats, connected accounts). It is unambiguously distinguishable from create_brand, update_brand, and get_brand in the sibling list.

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 two-phase flow (call WITHOUT confirm first to get the inventory, then again with confirm:true), and names the exclusion case: the account's first/anchor profile cannot be deleted this way and must be replaced from the app. There is no ambiguity about when this tool applies.

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 (destructiveHint, idempotentHint) by disclosing cross-device delete propagation, that only the roster entry is dropped, that already-rendered ads are untouched, and that the action is reversible via save_creator. This is exactly the behavioral context an agent needs for a destructive operation.

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

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

Two tightly written sentences, front-loaded with the action and id source, followed by the behavioral nuances. No filler; every clause carries information an agent would otherwise have to guess.

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 annotations covering the safety profile and no output schema, the description supplies the remaining essentials: scope, reversibility, cross-device effect, and what is not affected. 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?

Schema description coverage is 100%, so both parameters are already documented. The description reinforces the id source (list_creators) but says nothing about the optional 'brand' parameter, adding little beyond the schema. 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 (Remove) and resource (a saved creator) with scope ('from this workspace's cast') and the id source ('from list_creators'). This cleanly separates it from siblings like list_creators, find_creators, save_creator, and update_saved_creator.

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 names list_creators as the source of the id and points to save_creator as the recovery path, and explicitly says 'no confirm is needed' — useful invocation guidance. It does not explicitly contrast against update_saved_creator for modifying rather than removing, so it falls short of full when/when-not coverage.

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

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

Annotations already declare destructiveHint=true, and the description goes further by explaining that deletion defaults to the recoverable Trash, that permanent:true is irreversible, and that user confirmation should precede permanent deletion. This adds meaningful behavioral context beyond the annotations and does not contradict them.

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, purposeful sentences cover the operation, default behavior, parameter requirements, and the safety warning. The irreversible caveat is front-loaded before invocation details, 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 three-parameter delete tool with no output schema, the description supplies the essential operational details: recoverability, irreversibility, required confirmation, and how to obtain fileId. Given the existing destructive annotation, nothing critical is missing for correct selection and invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value by specifying that fileId comes from list_drive_files and by reinforcing that confirm:true is required. It also ties permanent:true to irreversibility, matching and slightly enriching the schema's parameter 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 specific verb and resource ('Delete a Drive file'), then adds the Trash-vs-permanent distinction so the operation is unambiguous. The resource is clearly Google Drive, distinguishable from siblings like delete_onedrive_file and update_drive_file.

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

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

Gives clear invocation guidance: fileId should come from list_drive_files, confirm:true must be passed, and the user should be consulted before a permanent deletion. It does not explicitly name alternatives or exclusions, but the sibling resource differences are evident from the tool 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 flag destructiveHint=true and idempotentHint=true, so the description doesn't need to restate danger. It adds the non-obvious detail that the underlying stored file is deleted too, not just the entry, and that unconfirmed calls are safe previews — behavior annotations don't convey. Lacks mention of irreversibility/restore options, 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?

Three tight sentences: destruction scope first, accepted inputs second, the confirm workflow third, plus a one-word cost note. Nothing is redundant with the title or schema, and the most consequential fact leads.

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

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

For a 3-param destructive tool with no output schema, it covers what is destroyed, how to preview, how to commit, which sibling supplies ids, and that it costs nothing. The preview return value is described informally, which is sufficient given no output schema exists.

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 exceeds it by explaining the tri-state meaning of confirm: absent = preview of what would be deleted, true = actual deletion, which the schema's 'true deletes' barely implies. It also notes ids/urls are alternatives rather than both required (consistent with 0 required params).

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 (PERMANENTLY delete) and a specific resource scope (images/videos from this brand's Library), and clarifies that both the library entry and the stored file are removed. This distinguishes it cleanly from siblings like delete_drive_file, delete_onedrive_file, and delete_brand.

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 exact workflow: call without confirm to preview, ask the user, then call again with confirm:true. It also names list_library as the source of ids, so the agent knows the prerequisite call and the safe sequence rather than just the tool's existence.

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, readOnlyHint=false, and openWorldHint=true. The description usefully adds that leads remain unaffected and readable, only delivery stops, and notes the action is read back from LinkedIn and free, which clarifies blast radius beyond the annotations.

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

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

The description is front-loaded with the core action and then adds only the effect scope and cost context. Every sentence carries useful information for deciding whether to invoke 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?

For a destructive webhook-removal tool with no output schema, the description covers what is removed, what is left intact, where the ID comes from, and cost. It could be slightly stronger by noting reversibility or prerequisites, but the annotations and schema cover most remaining behavioral needs.

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 fully documents subscriptionId, pageId, and adAccountId. The description repeats that subscriptionId comes from list_linkedin_lead_subscriptions but does not add new meaning for the optional pageId or adAccountId parameters.

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

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

The description states a specific verb and resource: remove a lead notification webhook. It also immediately distinguishes the effect from deleting leads themselves, which is critical next to sibling tools like list_linkedin_lead_subscriptions and subscribe_linkedin_leads.

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 clear: use this to stop real-time lead delivery for a subscription, with subscriptionId sourced from list_linkedin_lead_subscriptions. It does not explicitly state when not to use it or name subscribe_linkedin_leads as the inverse operation, though the context 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 already indicate destructiveHint=true, so the description adds meaningful context by disclosing that the item moves to the OneDrive recycle bin and is recoverable there. It also communicates the confirmation safeguard, which is valuable behavioral context beyond the schema and annotations.

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

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

The description is three short sentences with no filler. It front-loads the core behavior, then covers the parameter source and confirmation requirement. 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 simple two-parameter delete operation with no output schema, the description covers the action, the recoverability consequence, the source of the identifier, the required confirmation flag, and the user-confirmation step. Nothing essential is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100%, but the description adds important semantic guidance: fileId should come from list_onedrive_files, and confirm must be true. This compensates for the schema's inconsistency where confirm is described as 'REQUIRED true' but is not listed in the required array.

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 ('Delete') and a specific resource ('a OneDrive item'), and immediately clarifies scope by noting it is a recycle-bin move rather than a permanent purge. This clearly differentiates it from related siblings like update_onedrive_file, get_onedrive_file, and save_to_onedrive.

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 concrete usage instructions: pass fileId from list_onedrive_files, pass confirm:true, and confirm the exact file with the user first. This is strong practical guidance, though it does not explicitly name alternatives or conditions when this tool should not be used.

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, but the description adds non-obvious behavior the annotations cannot convey: the delete is recorded cross-device so the playbook will not reappear on the next sync, and the item is characterized as minor and re-creatable. It stops short of 5 because it says nothing about auth requirements 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?

Three short sentences, front-loaded with the action and identifier, then the durability semantics, then the confirmation guidance. No filler and every sentence 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?

Given rich annotations and a fully documented schema, the description supplies the remaining pieces an agent needs (id provenance, sync-proof deletion, no confirmation). No output schema exists but a delete returns little, so the only real omission is error/failure behavior.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, and the description's 'id' reference merely repeats that. The optional 'brand' parameter is not addressed in the description at all, so it adds no meaning beyond the structured fields.

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 saved playbook') plus the identifier source, and the id-provenance callout ('from list_playbooks') clearly distinguishes it from the sibling save_playbook and the list_playbooks read tool.

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

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

Gives clear usage context: the id must come from list_playbooks, and it pre-empts a confirmation workflow ('Minor + re-creatable, so no confirm needed'). It does not name a sibling alternative or an explicit when-not-to-use case, so it stops short of the 5 bar.

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 description benefits from that lower bar. It still adds non-annotation context: only custom skills are removable, and the deletion is described as minor/re-creatable so no confirmation is needed — useful impact guidance 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 short sentences, front-loaded with the primary action and scope, then the constraint, then the confirmation policy. 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 two-parameter delete with no output schema and full schema coverage, the description covers scope, the id source, non-deletable resources, and confirmation policy. It omits only failure behavior for an invalid or non-custom id, a minor gap given the annotations.

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 both parameters are documented in the schema, so the baseline is 3. The description reinforces that 'id' is a custom-skill id sourced from list_skills but adds nothing about the 'brand' parameter's semantics beyond what the schema states.

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') + resource ('skill') + scope ('CUSTOM skills', excluding built-ins and recipes), and it names the sibling that supplies the id (list_skills). An agent can immediately distinguish it from save_skill, get_skill, list_skills, and delete_playbook.

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 implies when to use it (removing user-created skills) and states a hard exclusion: built-in skills and recipes cannot be deleted. It routes the agent to list_skills for the id, but gives no guidance on what to do if the id is unknown/invalid or on prerequisites.

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

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

Annotations already cover read-only/idempotent/non-destructive, but the description adds substantive behavior: 0 credits, unmeasured is never zero with dated platform examples (Facebook post reach since 2026-06-15, Reddit impressions, Google Business), a 5-post baseline floor with an attributed external fallback, and the fact that conversions are invisible for organic posts. It also flags which output field to print verbatim.

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

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

Front-loaded with the purpose and the routing problem types, and the numbered refusals are scannable. It is dense and long, with some restatement of the title phrase and of the converting rules already in the schema, but nearly every sentence carries decision-relevant content.

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 diagnostic tool with no output schema, the description covers the interpretive rules an agent needs (unmeasured vs zero, baseline insufficiency, attribution of the external hook floor, and the `summary` field to print verbatim). It stops short of describing the rest of the response shape, which an agent would otherwise have to discover at call time.

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

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

Schema description coverage is 100%, so all three parameters are already documented with their defaults, limits, and the converting rationale — the description mostly restates the converting gate rather than adding new meaning. Baseline 3 applies when the schema carries the parameter burden.

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 framing ('what is WRONG with a given post and where the next edit goes') and explicitly contrasts with the sibling post_performance ('tells you which hook is AHEAD'). An agent can route between the two without opening either schema.

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

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

Gives an explicit decision tree: under-distributed → mine_angles/list_hooks/plan_variations, seen-but-not-held → plan_variations, seen-held-not-converting → offer rung with converting:false. It also states the exclusions in the four refusals, including the 24h too-early rule and that 'nothing here needs fixing' is a legitimate outcome.

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 destructiveHint annotation by spelling out what is actually destroyed (stored credentials, all provider tools stop working) versus what survives (already-published posts/campaigns). It discloses the non-obvious remote-side effect that the provider grant is NOT revoked and the account keeps working in other brands, and instructs the agent to relay the location for manual revocation from the unconfirmed response. That is exactly the kind of irreversible-side-effect disclosure a destructive 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?

Purpose is front-loaded in sentence one, followed by consequences and then prerequisites in a sensible order. Slightly over-signalled with all-caps warnings and a partial restatement ("IT NEVER REVOKES THE GRANT" is then re-explained as "rather than promising a revoke"), but almost every clause carries real information.

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

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

For a destructive, non-idempotent-looking-with-no-output-schema operation, the description covers the safety profile, the side effects, the provider-side persistence, the reconnect barrier, and the required confirm loop. Nothing an agent needs in order to call this safely and explain it to a user is missing.

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

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

Schema description coverage is 100%, so the schema already documents provider, account and confirm in detail, including the multi-account semantics. The description largely restates those constraints ("Name the provider", "call with confirm:true") rather than adding format or edge-case meaning the schema lacks. 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 ("Disconnect a third-party account from this workspace") and enumerates the provider families covered, so the agent knows exactly what domain it operates on. It stops short of distinguishing itself from the sibling leave_connector, which is the one adjacent tool an agent could easily confuse it with.

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 a concrete pre-call workflow: look up the exact provider id via list_connectors, name the provider to the user, then call with confirm:true. It also warns that reconnecting requires a browser so the agent cannot undo it. It never says when NOT to use this instead of leave_connector, leaving a real ambiguity between siblings unresolved.

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: 0 credits, save=true overwrites the saved profile while default only saves when none exists, the tool cannot ask the user so the caller owns verification, and domain-based resolution can silently hit the wrong company. This meaningfully elaborates the destructiveHint=true / idempotentHint=false profile the annotations only imply.

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, cost, and the verification warning in that order, with no filler sentences. The bala.com example costs a clause but is concrete and earns its space; slightly denser than it needs to be with parenthetical asides.

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 sketching the returned object ({name, products, logo, …}) and naming the two fields to verify. Field-level detail of the full returned profile is missing, but the essential decision-relevant output information is present for a 5-param, all-optional tool.

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

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

Schema coverage is 100%, so baseline is 3; the description still adds operational meaning to save (pass false until confirmed) and to the domain-vs-description fallback path. It also clarifies that the returned name/summary are the artifacts to inspect, which the schema does not express.

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: drafts a profile object from a domain, free-text description, or social handle, and names the downstream consumers (plan_ad / generate). It does not explicitly distinguish itself from near-siblings like create_brand, get_brand, or use_brand, which an agent may confuse with 'draft' when a profile is then saved.

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

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

Gives concrete when-to guidance: use before spending credits on research or renders, and pass save:false until the returned identity is confirmed. It does not name alternative tools (e.g. get_brand to fetch an existing profile, create_brand to start from scratch), leaving that comparison to inference.

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

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

Annotations only state the safety profile (openWorld, non-idempotent, non-destructive); the description adds substantial behavior beyond that: no re-render, lip-sync, background preservation, cost model ('Paid by length'), a dryRun quoting path, and the return value (localized video URL). That is exactly the context an agent needs for a paid, non-idempotent operation.

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

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

Three sentences, front-loaded with the differentiating capability ('WITHOUT re-rendering it'), followed by call essentials and cost/output facts. No filler; every clause earns its place.

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

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

For a 5-param, 100%-covered schema with a full annotation set and no output schema, the description supplies the remaining needed pieces: the cost/quote path and the returned URL. An agent has everything required to call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces that the script is read off the source and that `script` only overrides it, which is already conveyed by the schema's detailed property text, so it adds little beyond the structured fields.

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

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

The description gives a precise verb and resource ('Localize a finished video into another language') and even sharpens the scope with 'WITHOUT re-rendering it.' It does not name or explicitly distinguish itself from siblings like localize_ad or edit_video, so a 4 rather than 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 context is only implied: 'Pass the video and the language' explains the call, not when to choose this over localize_ad or another localization/edit tool. There is no when-not guidance or named alternative. The only real routing hint is the param-level note that script should be omitted unless the auto-transcript is wrong.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety bar is lower, yet the description still adds real behavior: the copy is independent so editing/cancelling never touches the original, it publishes even on channels where the original already went out, and defaults to one hour from now or the brand's next free slot. This materially qualifies the destructive/open-world hints rather than restating them.

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

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

Purpose is front-loaded and the size is justified for a 22-parameter tool, but the ALL-CAPS emphasis (NEW, ANY, INDEPENDENT) and the long em-dash clause in the first sentence add rhetorical bulk. Dense and mostly waste-free, yet it could be tightened by a line or two.

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 22-param mutation with no output schema, the description covers what gets copied, the override rules, the two scheduling modes, and the independence guarantee. The notable gap is what comes back from the call — presumably the new post's id for later reschedule/cancel — which an agent would need to chain into follow-up tools.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns an extra point by explaining the override model — caption, media, per-channel captions, title, description, tags and target are all copied but "ANY of those can be overridden in the same call", which tells the agent these params are optional deltas rather than requirements. It also frames the at-vs-useQueue duality, though it does not add detail beyond the schema's own wording for either.

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 ("Copy an existing scheduled or already-published post into a NEW queued post") and immediately distinguishes the near-miss semantics: a genuinely new post rather than a re-send. An agent can tell this apart from retry_scheduled and reschedule_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?

Gives three concrete motivating scenarios (run a creative again, reuse a post as a starting point, re-send after it went out) and an explicit exclusion with the correct alternative: "To re-fire only the channels that FAILED, use retry_scheduled instead." That is the when/when-not/alternative triad.

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?

Rich behavioral context beyond annotations: brand name/website pinning, real logo file placement, no image model for logo-only asks, product label check and its charges, and that it returns the new image URL. However, the annotations declare destructiveHint=false while the description advertises a removal mode that 'STRIPS text, branding or an object' — the tool only edits a copy, so this is not a direct contradiction, but the erosion of the safety signal caps it at 3.

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

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

Front-loaded with the core action and an example, but the body is a dense ~200-word run-on of semicolons and parentheticals covering billing, brand pinning, product label checks and edge cases. Every clause is informative, yet several could be tightened or moved to schema fields.

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 7-parameter generative mutation with no output schema, the description covers cost ('One image edit's credits'), return value ('returns the new image URL'), masking, brand integrity, and failure-adjacent modes. Nothing essential to invoking 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 86%, so the baseline is 3, and the description adds real meaning: logo:true triggers a no-model logo-file placement, removal:true suppresses brand re-adding, fixLabel:false disables lookup/check/re-print, mask is cross-referenced to generate_image. Only dryRun goes undiscussed, but the schema covers it.

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

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

States a specific verb and resource ('EDIT an existing image in place') plus the core constraint ('keep everything else'), and explicitly names the boundaries against generate_image and clone_static. An agent can tell exactly what this does and what it is not.

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 alternatives: 'For a new image from a prompt use generate_image; to rebuild a competitor's ad for your brand use clone_static.' Also gives conditional rules for logo-only asks, removal:true, fixLabel:false, and mask usage, so the agent knows when each mode applies.

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?

Well beyond the annotations (which only say non-read-only, non-idempotent, open-world, non-destructive), the description discloses cost (about 2 credits for the textChanges re-make), the free quality-score and over-edit flag in the reply, the preserve/relight lighting policy and how to force it, the faceRoute ownership requirement with the explicit "only on the user's say-so, never on your own" guardrail, and the previewFirstFrame safety valve that quotes without running the paid clip. It also sets a success heuristic ("one change per call holds best"), which is behaviourally useful and absent 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?

Information-dense but poorly structured: one unbroken block with run-on sentences, abrupt fragments ("previewAt picks the second"), and redundant framing ("SWAP AN OBJECT ... or EDIT an existing clip from a plain instruction"). The illustrative quotes ('change only the mug to red', 'make it nighttime', 'restyle it as claymation') repeat the same point three times. Most sentences do earn their place, but the packing makes key routing facts hard to locate.

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

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

For a 14-parameter, 3-enum, high-consequence generation tool with no output schema, the description covers what an agent needs: when to use it, which sibling to use instead, the cost model, the preview pathway to avoid paying for a bad edit, the ownership guardrail on real faces, the reply's scoring/flagging behaviour, and the clip-length sweet spot. Remaining details (job polling, per-engine differences) live in the schema or in get_job, so nothing critical is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, and the description genuinely adds above that: it explains the two-step previewFirstFrame → previewStill workflow, what literal:true disables (the preserve/lock wrapper), and that textChanges must carry every line at once in a single paid render. It leaves interactionId, engine routing and reference-material semantics to the schema, so it is additive rather than 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?

The opening states a precise verb+resource pair (swap an object in a video / edit an existing clip, video-to-video) and immediately scopes what stays fixed: "the motion, timing, framing and cut stay, the named thing changes." It also names the siblings it is NOT (post_edit, generate_video, render_ad, dub_video, recast_motion), so an agent can separate it from every near-neighbour in one read.

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 routing in both directions: use for object swaps and instruction-driven video-to-video edits, do not use for cuts/trims/end cards, new generation, spoken-language translation, or creator face replacement, each with the correct alternative named. It adds the special case where on-screen text changes in a template/design video should go through textChanges as one re-make rather than an edit, plus the practical constraint "best on 3-15s clips."

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 cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false). The description goes far beyond: it discloses which clients re-read the tool list vs which need a reconnect, that it reports the failure rather than faking success, the token-size rationale for the default roster, and that nothing is held out for safety reasons. This is rich behavioral context annotations cannot carry.

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

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

Front-loads the most important clarification ('IT IS NOT HOW YOU REACH A TOOL') before the details, and every section carries real signal. It is on the long side for a one-parameter tool, with some repetition around reachability, but little is genuinely wasted.

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

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

No output schema and one parameter, yet the description fully covers usage, alternatives, client behavior, rationale, and valid group values. An agent has everything needed to decide and invoke 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% for the single param, so the baseline is 3. The description adds the full list of valid group names (core, research, create, channels, channel_admin, analytics, ads, files, workspace, 'all') that the schema lacks (no enums), plus worked example calls, which meaningfully extends beyond the schema.

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

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

States a precise verb+resource: 'LIST a group of tools that is not in this session's roster.' It explicitly separates itself from call_tool and find_tools, so an agent knows exactly what this does and what it is not.

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 ('CALL THIS WHEN A WHOLE AREA IS IN PLAY') with concrete triggers for ads and analytics, names the alternative routes (call_tool, find_tools, ?tools=all), and states the client-compatibility condition that governs whether it will actually take effect.

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 read-only/idempotent/non-destructive, and the description adds non-obvious traits: zero credit cost and that occurrences are 'redacted' with only a 'shape-only echo of the inputs' returned. That redaction and shape-only detail is genuine behavioral disclosure beyond the annotations.

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

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

Dense and front-loaded: the retrieval action and key come first, then return contents, then cost. The closing 'This is what makes a bug reproducible' is mild marketing but does convey intent efficiently.

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 helpfully enumerates the return fields (status, connector, job id, workspace, shape-only input echo), which is what the agent needs to know. Only minor gaps remain, such as ordering or limits on 'most recent occurrences'.

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 fingerprint parameter is already documented as 'the `fp` value from list_errors'. The description restates this mapping but adds no format or syntax detail beyond the schema, so baseline 3 applies.

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

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

States a specific retrieval action on a named resource ('one error group in full by fingerprint') and names list_errors as the source of the fingerprint, so it is clearly distinguishable from the sibling that lists error groups.

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 parenthetical '(from list_errors)' tells the agent where the required fingerprint comes from, which is the key prerequisite. It lacks an explicit 'use this when... not that' exclusion, but the usage context is clear.

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

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

Adds material context beyond the annotations: column matching by name, the 100-row cap, a signal that the response says if more rows were left, and cost ('Free'). Those are real behavioral and operational facts an agent needs, and they align with readOnlyHint=false and openWorldHint=true.

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 what the export produces, then covers the create/write modes, history scope, row cap, and cost in densely packed sentences. No filler; every sentence carries an operational fact.

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

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

For a 5-param, open-world, non-read-only export with no output schema, the description covers modes, limits, output fields, and cost. An agent could invoke it correctly without reading further.

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 clarifies the create-vs-write distinction for parentPageId/databaseId and the meaning of historyDays. dataSourceId is only indirectly covered via 'matching its columns by name', so it isn't fully fleshed out beyond the schema.

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

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

States a specific verb ('Export') and resource ('the posting schedule to a Notion database'), plus the row shape (date, channels, caption, media link, status). That makes it distinguishable from generic siblings like save_to_notion or append_to_notion_page by scope, though it never names an alternative explicitly.

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

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

Explains the two operating modes clearly: create a new database under parentPageId (or private), or write into an existing one via databaseId. Also clarifies that historyDays includes already-published posts and that only 100 rows run at a time. No explicit when-not or sibling routing, which keeps it from a 5.

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

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

The description adds substantial behavioral context beyond the annotations: it creates a new deck every time, cannot append to existing user decks due to the drive.file scope, handles expired ad-library links by preserving copy and dates while noting the issue, and reports how many slides were affected. It also specifies the required Google Drive connection. This goes well beyond what the annotations alone disclose and contains no contradictions.

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

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

The description is front-loaded with the primary action and outcome, and each sentence generally adds useful operational detail. It is somewhat long and includes a few extended parenthetical explanations, but it remains readable and information-dense rather than wasteful.

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

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

Given the absence of an output schema and the external side effect of creating a Google Slides deck, the description is complete enough for correct invocation. It covers the return value (presentation id and URL), prerequisites, creation behavior, scope limitations, and an important edge case involving expired creative links.

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 limit, title, and collection with defaults and formats. The description does not add meaningfully richer parameter semantics beyond what the schema provides, so the baseline score of 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 states a specific verb and resource: turning a swipefile collection into a Google Slides deck with one slide per saved ad. It clearly explains what is produced and what each slide carries, but does not explicitly differentiate this tool from sibling tools such as create_doc, save_to_drive, or list_swipefile.

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 clear context for use ('the thing a marketer actually presents to a client or a team'), states prerequisites ('Needs Google Drive connected'), and discloses an important constraint ('Creates a NEW deck every time' and cannot add slides to an existing deck). However, it does not explicitly tell the agent when to choose this over alternative tools or name a specific sibling to use instead.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=true and destructiveHint=false, and the description is consistent with a write-to-brand operation. Beyond that it discloses cost ('FREE — a keyless store lookup or one read of the homepage'), the failure mode (ambiguous/unknown app returns 0 screens and saves nothing), and the success side effect (screens saved to the brand as durable URLs, immediately usable). Only the exact return payload shape is left implicit.

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

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

It is front-loaded with the purpose and trigger, then stacks preconditions, fallbacks, cost, and failure handling in a logical order with zero filler sentences. It is on the dense/long side for a three-parameter tool and could compress the web-app fallback clause, but 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?

For a tool with no output schema and an external-dependency (open-world) lookup, the description covers inputs, the no-store fallback, the zero-result failure behavior with guidance not to retry, cost, and where results land. An agent has everything needed to call it once correctly and interpret the outcome.

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 appName defaults to the saved brand's name and that storeUrl takes a link or package id, so the description largely restates it ('storeUrl ... is read exactly; else pass appName'). It does add genuinely new meaning for storeUrl-less web apps — falling back to pictures the product's own website labels as its interface. With the schema doing the heavy lifting, this sits at the baseline plus one useful addition.

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

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

The description names a specific verb and resource — pulling real Google Play / App Store screenshots into the workspace brand — and distinguishes itself from siblings like fetch_asset or list_product_photos by scoping it to app-store screens used by screen-hungry native formats. An agent can tell exactly 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?

It gives an explicit trigger condition ('brand has 0–1 app screens on file'), a concrete downstream use (make_template_ad with template:'app-ui-tour'), a natural-language user phrasing, and a pre-emption rule ('Call it before telling the user you have no screenshots'). It also steers the agent away from retrying with guessed names, which is an explicit when-not.

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?

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety behavior is covered. The description adds useful behavioral context beyond the annotations: it explains that a generated asset reference or URL is resolved into a clickable absolute URL and a direct download URL.

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, well-structured sentence that front-loads the action, the accepted input, and the resulting output. Every phrase contributes necessary information with 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?

For a low-complexity tool with full schema coverage and rich annotations, the description is nearly complete: it covers what the tool does and what it returns, even though no output schema exists. It omits only alternative-tool guidance and does not address the optional 'name' parameter.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description repeats the URL input example and does not mention the optional 'name' parameter or add syntax beyond what the schema provides, making 3 the appropriate 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?

The description uses a specific verb ('Resolve') and a precise resource ('generated asset reference'), and it states the output form. It is clear, but it does not explicitly name or distinguish itself from any sibling tool such as get_drive_file or fetch_social_data.

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 describing the accepted input ('a /generated/… path or any URL'), but it never states when to use this tool versus alternatives or any exclusions. Guidance is present only at an implied level.

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 (non-read-only, open-world, non-idempotent, non-destructive), and the description adds real behavioral context beyond them: it consumes credits, enforces an allowlist that rejects other paths, and returns raw provider JSON that is large and messy. That is materially useful disclosure for a mutation-adjacent, credit-spending 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?

Front-loaded with the purpose and example, with the prefer-alternatives warning positioned after the core statement. The long enumeration of platform families is density rather than filler, since it communicates the allowlist scope, though it is the longest part of the block and pushes the WARNING late.

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 generic passthrough with a 2-param schema, an allowlist constraint, and no output schema, the description supplies everything needed: scope, allowlist, param-name variability, cost, and return-format expectations. 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 coverage is 100% and the schema already documents path and params, so the baseline is 3. The description goes further by noting that param names vary per endpoint (handle for profiles, query for keyword searches, subreddit for Reddit) and gives example shapes, which is genuine added meaning.

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 precise verb and resource — 'Generic escape hatch for any ALLOWLISTED long-tail social/web endpoint' — and explicitly frames it against the dedicated search_* siblings. An agent knows exactly what class of call this performs 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 states when to use it (endpoints the dedicated search_* tools don't cover), when not to (a WARNING says prefer the dedicated search_* tools because output is large/messy), and gives a concrete invocation example. Routing guidance is explicit rather than inferred.

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 genuinely useful non-schema context: it bills the discovery model's token cost, carries no ad-data charge, and is free during a new account's first-brand setup. That complements the annotations (readOnly=false, openWorld=true, non-idempotent), while the web-search grounding signals nondeterminism. It stops short of describing result size or 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?

Two dense sentences with the core action front-loaded, followed by mode semantics and then cost implications. No redundant or filler text.

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

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

For a 2-parameter tool with annotations and no output schema, the description covers action, modes, and billing, which is most of what an agent needs. The notable gap is that it never says what comes back (a list of brands, ads, etc.), which matters since no output schema exists.

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 enum already documents each mode with the same wording used in the description, so the description adds no meaning beyond the schema. The domain parameter is only illustrated in the schema, not elaborated in the description.

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

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

States a specific verb ('Discover') plus the resource ('competitor / similar / adjacent brands from its domain') and names the grounding mechanism (Claude + web search). An agent can distinguish it from sibling discovery/analysis tools like competitor_teardown or pull_competitor_ads, which imply deeper analysis or ad retrieval.

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 three modes and their differing behavior (default excludes the searched company; inspiration includes it and surfaces best relevant ads), which tells the agent which mode to pick. It does not explicitly contrast with sibling tools such as pull_competitor_ads or set_competitor_watch, so routing is clear but not fully exclusionary.

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?

Discloses the cost model in detail (one credit per platform × query call with defaults, one per enriched profile, free repeats inside 20 minutes), what enrichment actually returns, and that marketplace:true depends on the Meta connector. That is substantive context beyond the annotations, which only mark it non-read-only and open-world.

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 what it scans and how it ranks before the cost and follow-on detail; dense and slightly run-on in the middle, but nearly every sentence carries invocation-relevant information.

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

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

With no output schema, the description still explains what comes back — ranked creators scored on median views, engagement rate and niche frequency, with follower counts and public contact fields on the top rows. Combined with cost, connector requirement and next steps, an agent has everything needed to call it and use results.

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, but the description adds genuine meaning for enrich (top 3 per platform, 1 credit each), marketplace (also queries Meta's creator directory and appends those rows), and the cost implication of queries — more than the schema alone conveys.

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 chain (scan, fold into creators, rank) over a named resource (TikTok/Reels/YouTube posts) scoped to a niche, and the 'real people, not AI actors' framing plus named ranking signals make it unmistakable next to search_posts or list_creators.

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

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

Names concrete use cases (influencer sourcing, UGC casting, partnership prospecting) and then routes the agent to the exact follow-on tools — save_to_swipefile for shortlisting, fetch_social_data / instagram_profile for checking, generate_text for outreach, manage_meta_partnership_creator for Partnership Ads.

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

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

Annotations declare readOnlyHint=false and openWorldHint=true, and the description is consistent with that — it fetches from TikTok's current catalog and returns a durable mp3 (implying materialization/side effects). However, it never explains why the call is not read-only: whether the mp3 is saved to a library, whether repeated calls are non-idempotent, or what happens when nothing matches. With annotations covering safety and idempotency, that residual gap justifies a 3 rather than higher.

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

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

Two compact sentences plus a closing sentence, no filler, and the input modes and return shape are front-loaded. The phrasing is dense and slightly elliptical ('a durable mp3 and where it starts and lands', 'pick takes another candidate'), which costs a small amount of immediate parseability but not enough to waste space.

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 3-parameter, all-optional lookup tool with no output schema, the description covers the input modes, the return payload shape, and the fallback to generate_sfx — enough to call it correctly. What is missing is the lifecycle around the returned mp3 (is it persisted, where, and what does an empty result look like), which matters given the non-read-only annotation.

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 all three parameters are already documented, and the description largely restates them (name/moment/link, pick another candidate). It adds only marginal meaning: that 'named/described' queries resolve against what TikTok uses now, and that pick is a follow-up to a previously returned candidate list. Baseline 3 applies 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?

The description names the resource (a sound) and the three lookup modes — by name ('the FAAAA sound'), by moment ('bad news reaction'), or by link — and states the output ('a durable mp3 and where it starts and lands'). It also names the sibling it is not (generate_sfx) for sounds that don't exist, so an agent can distinguish it without opening the schema. The only weakness is the telegraphic opening fragment, which reads more like a caption than a verb-led statement.

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?

Clear routing is given: this tool when the sound exists in some form (name, moment, link), generate_sfx when it doesn't. It also explains the candidate-picking path ('pick takes another candidate' after a prior list), which is an implied retry/selection workflow. It gives no guidance relative to other audio siblings like generate_music or search_tiktok, so context is clear but not exhaustive.

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 readOnly/idempotent annotations, the description discloses meaningful behaviors: failing tools or those needing missing connectors are 'ranked last and marked, never hidden,' and the meaning of 'no recent calls' is explained. It also clarifies how credit cost is presented (free vs. live per-model figure). This is rich behavioral context beyond the annotations.

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

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

The description is dense but efficient, covering purpose, usage trigger, output contents, and behavioral nuances in a few sentences. It uses dashes to pack information without redundancy. Slightly long, but every sentence serves a purpose and the key scoping statement is front-loaded.

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 stating exactly what each returned row contains (parameters, credit cost, health). It also covers the critical next step (call_tool) and the onlyHealthy filter. For a discovery tool with optional parameters, this is complete context for an agent to use 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?

The schema covers 100% of parameters with descriptions, so the baseline is 3. The tool description itself does not add parameter-level semantics beyond what the schema already provides; it only reiterates the onlyHealthy behavior in prose. No additional meaning is given for group, limit, or query beyond their schema 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?

The description states a clear verb and resource: 'Search EVERY Hermoso tool ... by name, task or group.' It distinguishes itself from the short default tool list and from siblings by emphasizing that it covers the full tool set and returns metadata (parameters, cost, health). This leaves no ambiguity about what the tool does.

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 an explicit trigger condition: 'Use it the moment the user asks for something you do not see a tool for' and provides concrete examples (campaign, ad set, lead form). It also instructs to follow up with call_tool. It does not explicitly name when-not-to-use alternatives like the list_* tools, so it stops short of a perfect 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?

Goes well beyond the annotations: no AI model, ~30s runtime, billed for compute only, returns a NEW video and leaves the original untouched — this materially clarifies the non-destructive, non-idempotent profile. It also warns that copy is authored by the caller and stats must never be fabricated.

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 the key constraint (EXISTING video), then behavior, then cost/runtime, then return semantics. Dense — one long paragraph with parentheticals — but every clause carries information; 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?

No output schema, but the description covers return semantics (new video, original untouched), cost and runtime, and the toggles. Minor gap: it doesn't say whether the result is returned inline as a URL or as a job to poll, which matters for chaining.

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