Hermoso

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds valuable context beyond that: the tool costs '~a transcription call' and extracts specific components such as voiceover vs on-screen text, beat lists, and frame timestamps. This gives the agent accurate expectations about cost and 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?

Three sentences carry all essential information: output contents, intended use, and cost. The most important scoping information is front-loaded, with no filler or redundancy.

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

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

Despite having no output schema, the description clearly lists what the agent will receive (transcript, beat list, duration, timestamps), what input is needed (URL), and what tradeoff to expect (transcription cost). For a read-only analysis tool with a single parameter, this is complete.

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

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

Schema description coverage is 100%, and the input schema already fully documents the url parameter. The description adds only light context that the URL should point to a video ad for structural analysis; it does not materially expand on the schema's parameter 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 states a specific verb ('Break down'), a specific resource ('a video ad'), and enumerates concrete outputs: verbatim transcript, beat list, duration, and sampled frame timestamps. This clearly distinguishes it from editing/generation siblings like edit_video, clip_video, and generate_video.

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

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

The description gives an explicit use case: 'Use to study a reference/competitor ad before remixing its structure.' It provides clear workflow context for when to invoke the tool, though it does not explicitly name exclusion criteria or competing alternatives.

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

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

Annotations already communicate that this is a write operation (readOnlyHint=false), non-destructive (destructiveHint=false), non-idempotent (idempotentHint=false), and open-world (openWorldHint=true). The description adds useful context about the document eligibility model and end-of-doc positioning. 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?

A single front-loaded sentence that puts the action first and then gives the essential eligibility detail. There is no filler, though the embedded dashes and clauses make it slightly dense to parse.

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 tool with no output schema, the description covers what the tool does, where it appends, which documents are eligible, and how to obtain the documentId. It does not mention formatting behavior like newline handling before appended text, but this is minor given the annotations already cover the safety profile.

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 meaningful value by broadening documentId beyond the schema's narrower 'the document id from create_doc', explaining that list_drive_files is also a valid source for user-provided docs. The text parameter is not enriched 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?

The description states a specific verb, resource, and position: 'Append text to the end of a Google Doc'. It also defines the tool's scope ('Hermoso can reach') and distinguishes it from siblings like append_to_sheet by naming the Google Doc resource explicitly.

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

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

The description clearly tells the agent when the tool applies — for any reachable Google Doc — and which documents qualify: ones Hermoso created or ones the user shared via the picker. It also routes the agent to create_doc and list_drive_files for obtaining the documentId. It does not explicitly name excluded alternatives like update_doc or read_doc.

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 convey readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the mutation profile is established. The description adds useful access-scope context ('Hermoso can reach') and the row structure, but it does not disclose details such as append behavior at the end of the sheet, duplicate rows on retry, or any response shape.

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

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

Two sentences, front-loaded with the core action, and every clause earns its place by explaining reachable sheets, ID provenance, and row structure. No fluff or redundancy.

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

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

Given the annotations, the 100% schema coverage, and the tool's moderate complexity, the description provides enough for an agent to invoke it correctly. It covers resource eligibility and parameter sourcing. It lacks explicit guidance on what the tool returns after appending, but that is not essential 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%, so the baseline is 3. The description adds value by telling the agent exactly where to get spreadsheetId ('pass the spreadsheetId from create_sheet', 'find its id with list_drive_files'), which is actionable guidance beyond the schema's generic parameter description.

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

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

The description states a specific verb ('Append rows') and a specific resource ('a Google Sheet'), and adds meaningful scope: sheets Hermoso created or the user handed over via the file picker. It is clearly distinguishable from sibling tools like append_to_doc and update_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 description gives clear context for when to use the tool by explaining which sheets are eligible and how to obtain the spreadsheetId from create_sheet or list_drive_files. It does not explicitly contrast with alternatives like update_sheet or clear_sheet_range, so it stops short of a 5.

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

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

The description discloses far more than annotations: it is bounded/resumable/quoted, runs as a dry run by default, requires confirm:true to import, and returns a cursor to continue. It explicitly warns that backfilled posts are weaker evidence, labeled 'backfilled', and that unattributed posts never vote on hooks. This goes well beyond 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?

The description is long but every sentence earns its place: supported channels with denials, the dry-run/confirm workflow, the evidentiary caveat, and the 'never guess a hook' rule. It is front-loaded with the core purpose and then progressively adds actionable constraints. The capitalization draws attention to critical warnings without being noise.

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, the description tells the agent what it will get (a count and a cost quote, a cursor to resume), what will happen on confirm (import with backfill labels), and what the limitations are (unattributed posts, no voting). It also covers edge channels and the reasoning for exclusions. Nothing essential is missing.

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

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

Schema coverage is 100%, so the schema already documents all five parameters (limit, cursor, channel, confirm, accountRef). The description adds semantic context around confirm ('dry run by default', 'pass the returned cursor to continue') but doesn't add meaning to limit or accountRef beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with a specific verb ('Import') and resource ('this brand's PAST posts from a channel'), and immediately states the purpose: feeding the 'which hook works' analysis with historical data. It clearly distinguishes this from list_published_posts or collect_post_metrics by emphasizing the backfill/import nature and the channel support 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?

The description explicitly says when to use it (to draw on history predating Hermoso recording) and names excluded channels with reasons (LinkedIn, Reddit, X, Google Business, Telegram). It even states the dry-run/confirm workflow, which is a usage instruction. The alternative tools are implicit through sibling names but the conditions for choosing this tool are clearly stated.

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

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

Even though readOnlyHint is already true in annotations, the description adds substantial behavioral detail beyond annotations: how to quote the price (priceUsd per period, not monthlyUsd), the member-scoped omission of the owner's card and auto-reload settings, and the warning never to tell a member there is no card on file. This is exactly the kind of context annotations cannot express.

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

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

The description is long but information-dense, with the core purpose front-loaded and every subsequent clause adding operational or safety-relevant meaning. The member-scope warning is clearly emphasized and earns its length.

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

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

With no output schema, the description fully enumerates what the caller can expect to learn: current plan details, credit balance, auto-reload status, card presence, own admin rights, and the member-scope variation. For a zero-parameter read-only tool, nothing essential is missing.

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

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

The tool takes zero parameters and the empty input schema documents that fully, so there is no parameter burden for the description to carry. The description instead correctly uses its space to explain the result semantics and permission-scoping rules.

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 ('Show this account's billing at a glance') and enumerates exactly what data is returned: plan id/label/actual price, credit balance, auto-reload state, card on file, and the key's admin rights. It clearly distinguishes this read-only status tool from mutation siblings like upgrade_plan and set_auto_reload.

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 says 'Call it before upgrade_plan / set_auto_reload to know what's possible' and explains that members have read-only billing. It also gives a concrete when-not-to-infer rule: in a shared team workspace, members only see plan and balance, and must not be told the card is absent.

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

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

Discloses a large amount of behavioral context beyond annotations: saved-card vs no-saved-card flow, billing-admin requirement, quote validity of 10 minutes, idempotent retry with quote_token, Stripe checkout behavior with no redirect, and the machine-payment 402 challenge. The description contradicts no annotation and gives an agent an accurate mental model of side effects and prerequisites.

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

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

The description is long but well-structured, front-loading the common path before covering the no-card, machine-payment, and auto-reload edge cases. Some phrases, like the opening 'Out of credits?' and the repeated 'the same packs, the same prices, the same credits,' are somewhat filler, but the density of essential operational detail justifies most of the length.

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

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

With no output schema, the description carries the full burden of explaining expected results and behaviors. It covers the list output format, the quote step, the charge step, the checkout URL, the machine-payment challenge, permission requirements, and the auto-reload alternative. For a high-stakes payment tool, this is exceptionally complete; an agent has everything needed to call the tool correctly and understand consequences.

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?

Although the schema already describes each parameter, the description adds crucial semantic meaning: pack is omitted to list packs, confirm:true actually charges the card, and quote_token binds the exact pack and price with a 10-minute validity, making retries idempotent. This is significant extra value beyond the input schema, especially for a payment flow where misuse could cause unintended charges.

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: top up credits with a credit PACK, including listing, quoting, charging, and generating a checkout link. It explicitly contrasts this with subscriptions and auto-reload, and even names the sibling set_auto_reload, so an agent can distinguish it from related billing tools without ambiguity.

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

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

Provides explicit call patterns: no arguments to list packs, pack to quote, confirm with quote_token to charge, and a separate machine-payment path for credentialed agents. It clearly states when not to use the tool (subscriptions are managed by a person) and points to set_auto_reload for preventing future low balances, giving an agent both when-to-use and when-to-use-an-alternative guidance.

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

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

Annotations already mark destructiveHint=true and readOnlyHint=false, so mutation risk is known. The description adds valuable behavior: same permissions/account/result as direct call, validation against the target tool's schema with error responses rather than silent defaults, and refusal-with-reason behavior. Each of these goes beyond the annotation booleans.

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

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

Four sentences, dense but each adds a distinct fact: capability, provenance, host limitation, validation and refusal behavior. Slightly longer than necessary but well organized and front-loaded with the core capability.

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

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

Covers invocation source, host limitation, validation behavior, and failure modes. No output schema exists, so return format is not documented, but for a dynamic dispatcher the critical unknowns (how to find the name, when to use it, what happens on error) are addressed.

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 described. The description reinforces 'exact name from find_tools' and 'args exactly as its own schema takes them', which adds practical guidance about provenance and format beyond the schema's generic object description.

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

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

The description clearly states it runs any Hermoso tool by name, gives the exact use case (hosts that can't reload tool lists), and differentiates it from enable_tools. It names the resource (any tool by name) and the action (run) with specific scope.

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

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

Explicitly says to get name/args from find_tools first, explains when this route is needed (claude.ai, ChatGPT hosts that can't reload tool lists mid-conversation), and contrasts with enable_tools. Also discloses refusal cases: missing connectors or host policy.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds contextual behavior beyond annotations: the queued-only restriction and the cannot-unsent consequence, which are valuable for an agent invoking cancellation.

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 carry the full message. The action is front-loaded first, followed by the id source, the temporal boundary, and the alternative tool. There is 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 single-parameter cancellation tool, this is complete: the agent learns what to do, which id to use, when it works, what to do after publication, and the destructive/idempotent behavior from annotations. No output schema is a minor gap for such a simple mutation.

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

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

The schema already provides 100% coverage for the single id parameter, including its source in the description. The tool description repeats that the id comes from list_scheduled but does not add new semantic depth beyond what the schema documents. 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: 'Remove a queued post before it goes out.' It clearly differentiates from siblings like schedule_post, list_scheduled, reschedule_post, and duplicate_scheduled, and even names manage_meta_post as the alternative for deleting published posts.

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 when the tool works: 'Only works while it is still queued.' It also gives the id source ('Get the id from list_scheduled') and names the alternative tool for published posts, making the decision boundary explicit.

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

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

Annotations are mostly negative hints (readOnlyHint false, destructiveHint false), so they do little to inform behavior. The description adds meaningful behavioral context: it preserves performance, lip-sync, and background sound, and it returns the served URL and is paid. This goes beyond what annotations provide, though it could say a bit more about the mutation's side effects.

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

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

Two dense sentences with no wasted words. The primary behavior is front-loaded, then usage guidance, the sibling alternative, cost, and return value are each given in a compact clause. Every part earns its place.

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

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

For a 2-parameter tool with no output schema, the description covers the main behavior, preservation guarantees, use case, alternative path, cost, and return value. The input schema fills in the remaining parameter details. Nothing essential is missing for an agent to invoke this 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 description does not need to compensate for missing parameter docs. The schema already describes video and voice, including examples and the voice-clone caveat. The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('Swap the narration') and resource ('finished video'), and immediately distinguishes itself from dub_video. The description makes it clear what the tool does and how it differs from the closest sibling.

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

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

Explicitly states when to use it ('user likes the video but wants a different narrator voice') and when not to ('use dub_video only for language translation'). Also notes it is Paid, giving the agent a clear decision boundary.

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

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

Annotations already mark the tool as read-only and non-destructive, and the description adds rich behavioral detail beyond that: it is a 'flat 1-credit check,' it pulls Meta's actual live policy pages, every flagged issue quotes Meta verbatim, it provides a compliant rewrite, and it 'never changes the creative.' This is exactly the contextual behavior an agent needs to set expectations and avoid misuse.

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-loaded: the first sentence states purpose, target, and cost; the second explains method and output; the third removes ambiguity about mutation; the fourth gives concrete use cases. Every sentence earns its place, and there is no repetition of schema or annotation 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?

Even though there is no output schema, the description fully compensates by specifying the verdict values ('pass / fix / block'), the quoting-and-rewrite behavior, the live policy source, the cost, and the target scenarios. Combined with 100% schema parameter descriptions and read-only annotations, an agent has everything needed to select and invoke this 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 all four parameters. The description adds meaningful semantic context on top: 'copy' is clarified as 'ad copy / script / on-screen text,' 'claims' maps to 'claims / proof points the ad makes,' and 'category' is explained as helping 'pick the relevant policy pages.' This goes beyond the baseline and connects the parameters to the tool's internal behavior.

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: 'Pre-flight ad copy against Meta's REAL, live Advertising Standards.' It also names the exact output form ('verdict (pass / fix / block)') and explicitly contrasts it with editing ('It's a check, not an edit'), which separates it clearly from sibling creative tools like plan_ad, render_ad, or post_to_meta.

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 trigger conditions: run it before launching ads, especially for regulated-adjacent categories such as health, finance/crypto, alcohol, dating, gambling, or for any strong/absolute/guaranteed claim. It does not name alternative tools or state when not to use it, so it stops short of a full 5, but the when-to-use guidance is clear and actionable.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, so the destructive nature is known. The description adds valuable behavioral context beyond that: the two-call confirm flow, the echo mechanism (confirmCells) that catches naming mistakes, the fact that there is deliberately NO default range, that the clear is read back and reported as confirmed only if the range is truly empty, and that rows are left in place. This is rich, non-obvious behavioral disclosure that goes far beyond the structured data.

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. The description front-loads what the tool does, then explains the safety protocol, the echo rationale, the no-default-range design, and the alternative tool — all in roughly 110 words. Nothing is wasted or redundant with the schema or annotations.

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

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

For a destructive mutation tool with 5 params, no output schema, and only partial schema coverage, this description is remarkably complete. It covers the operation, the safety workflow, the exact parameters to set in each call, a common failure mode, the absence of a default, the post-condition verification, and points to the sibling for a related but different task. There is no meaningful gap an agent would face when invoking 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 only 40%: 'range' and 'confirmCells' have descriptions, but 'confirm' and 'sheetUrl' and 'spreadsheetId' do not. The description partially compensates by explaining confirm (the two-call protocol) and confirmCells (echo the filled-cell count the unconfirmed call reported). It doesn't explain the relationship between sheetUrl and spreadsheetId, but the core usage semantics of the non-obvious parameters are well covered. With 5 params and 40% coverage, the description carries a large share of the burden and does so effectively.

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

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

The description clearly states the verb 'Empty a range of cells in a Google Sheet' and specifies a resource (cells in a range) and scope (leaving rows in place). It distinguishes itself from the sibling manage_sheet_tabs by explicitly naming it as the alternative for removing a whole tab, and from other sheet operations by focusing specifically on clearing a range.

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 and how-to-use guidance: call once without confirm to get the filled-cell count, show the user that number, get confirmation, then call again with confirm:true AND confirmCells set. It also explicitly names the alternative for a different task: 'To remove a whole tab instead, use manage_sheet_tabs.' This is exactly the kind of exclusionary guidance that helps an agent decide.

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 carry essentially no protective hints (all false), so the description bears the full burden — and it delivers extensively: the ffmpeg-only pipeline, subject-aware single-crop reframing with its rationale (per-frame crops shimmer), fallback behavior (dead-centre when no subject found), cost model (~7-credit hold plus per-clip vision event), burned-in subtitle styling, approximate non-word-level timing caveat, and explicit guidance to read reframedToSubject/reframeWhy/captionsBurned off the result rather than assume. No contradiction with the annotations exists; readOnlyHint=false is consistent with a creating 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?

The description is long (~350 words) but every section earns its place for a tool this complex: novel reframing behavior, cost, input constraints, and caption defaults are all things an agent could not infer from the schema. Key facts are front-loaded (what it does, output shape, core trade-off of speed via no video-model renders). The reframe explanation could be tightened without losing meaning, which prevents 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?

With no output schema and no protective annotations, the description must cover return values, defaults, failure modes, and edge cases — and it does: clips[] fields (mp4 URL, title, hook, caption, score, timecode), defaults for count (4), aspectRatio (9:16), captions (true), the truncated flag, refund behavior on unsupported sources, and the captionNote/reframeWhy diagnostic fields. This is complete enough for an agent to select, invoke, and interpret the result correctly.

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

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

Schema coverage is 100%, establishing baseline 3. The description adds genuine value above the schema: for captions it details the visual style, the mute-viewing rationale, the bare-clip fallback, and the result fields to inspect; for video it adds the ~15s/~600MB limits, the 40-minute analysis cap with truncated:true, and the unsupported-source failure behavior. It does repeat some schema content (e.g., aspectRatio 'keep'), so it doesn't reach 5.

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

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

The opening sentence states a specific verb+resource+output: 'Cut ONE long video into several RANKED, ready-to-post short clips' with the intended source types (podcast, webinar, interview, conference talk). It clearly differentiates from siblings like edit_video, reframe_video, and stitch_video by emphasizing the one-to-many ranked-clips transformation and ready-to-post output.

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

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

Provides explicit usage context: three accepted input categories (external watch URLs, direct media URLs, Hermoso /generated/ URLs), hard exclusions (TikTok/Instagram/Facebook links, age-restricted/private/geo-blocked/LIVE content), and a concrete fallback instruction ('ask for a direct file or an upload rather than retrying'). However, it never names sibling tools such as edit_video or reframe_video to state when those should be chosen instead, so differentiation guidance is implied rather than explicit.

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

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

The description goes well beyond the annotations: it explains that metrics accrue and skips already-taken readings (aligning with idempotentHint=true), that ABSENT is recorded with a reason rather than zero, that failed reads are recorded as 'could not tell', and that X is skipped by default for cost reasons with the skip always reported. It also discloses the credit cost implication, which the annotations do not capture.

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 not bloated; each sentence carries a distinct behavioral fact. It front-loads the core purpose and then covers accrual, data semantics, and cost. Some repetition about skipping occurs ("skips the ones already taken" and "X IS SKIPPED BY DEFAULT"), but it remains focused and readable.

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, the description thoroughly covers what the agent needs to know before calling: the timing logic, the data recording semantics (ABSENT vs zero, 'could not tell'), the cost trigger, and the skip reporting so missing channels are not misinterpreted. The parameters are fully covered by the schema, and annotations supply the safety profile, so no critical context 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. The description adds value beyond the schema by revealing that X is skipped by default, that the skip is always reported, and that the operation is free except for X, which enriches the meaning of includeMetered:true beyond the schema's 'bills credits' note. max gets no additional semantics, but the run cap is already adequately described in the schema.

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

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

The description states a specific verb ('Fetch') and resource ('this brand's recorded posts') plus the storing action ('as a time-series'). It conveys the unique accrual logic (read at ~24 hours and ~7 days) that distinguishes it from a one-shot performance reader like post_performance, so the agent can tell what this tool alone 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 clear situational context: it collects readings that are due and skips ones already taken, and it explicitly instructs when to pass includeMetered:true and to warn the user about credits. However, it never names sibling alternatives or says when NOT to use this tool in favor of another, so the when-to-use vs alternatives guidance is implicit rather than explicit.

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

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

Beyond the readOnlyHint annotation, the description discloses that omitting `ads` triggers a live Meta ads pull that 'spends a credit or two', and that passing ads makes it free. It also explains the auto-tailoring to the saved brand and that 'longest-running = proven winners', providing meaningful behavioral detail not available from annotations alone.

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?

Although longer than a typical one-liner, every sentence carries unique operational information: purpose, deliverables, contract for ads, credit cost, and personalization. The structured 'CONTRACT:' marker and front-loaded outcome ('actionable playbook') make it easy to parse despite the density.

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

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

The description covers what the tool produces (a componentized playbook), how to control input (ads vs. auto-pull), cost behavior, personalization, and the source of data. With no output schema, the description's enumeration of the playbook sections is essential and sufficiently complete for an agent to invoke the 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?

The schema already has full 100% coverage, so the bar is at 3. The description adds value by clarifying the credit implication of omitting `ads`, calling them 'raw ad objects', and reinforcing that `domain` refines the auto-pull page match. This is modest but genuine added semantics 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?

The description clearly identifies the verb ('Tear ... down') and the resource ('a competitor's ad strategy'), then enumerates the exact deliverables (hook mix, themes, white space, counter-plays, avoided territories). This makes it easily distinguishable from sibling tools like pull_competitor_ads or research_ads, which remain precursors or broader alternatives.

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

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

The description gives a concrete workflow: pass `competitor` and either supply `ads` from a prior pull or let the tool auto-pull. It explicitly states the trade-off (credit spend vs. free with ads), giving an agent clear guidance on when to choose each path. It does not explicitly list alternatives or exclusions, but the context is sufficient.

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: the conversion happens server-side by Microsoft ('nothing is re-encoded here'), the result lives at a durable Hermoso URL while 'Microsoft's own conversion link expires within minutes', and it only needs OneDrive connected with 'no new permission'. These are exactly the non-obvious traits an agent must know to use the result safely. No contradiction with readOnlyHint/destructiveHint.

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 purpose, then each subsequent block earns its place: format coverage, use cases, the JPG dimension constraint (in caps, drawing attention), URL durability warning, and permission note. The enumerated format list is somewhat verbose but serves the differentiator function. Slightly longer than the tightest possible version, but nothing 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 4-parameter tool with no output schema, the description covers the essentials: operation, supported formats, concrete use cases, a hard parameter constraint, the durability of the output URL, and the auth prerequisite. The one gap is that it never explicitly states the return shape — it strongly implies the durable URL is returned ('you can pass straight to a render or a post') but does not say so directly, and error behavior is undocumented.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters, establishing a baseline of 3. The description does add one meaningful nuance beyond the schema: it stresses that JPG requires BOTH width AND height together ('Microsoft refuses the call without them'), which clarifies the interdependence of those parameters. This is useful but marginal.

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 phrase 'Turn a file already in the user's OneDrive into a PDF or a JPG' gives a specific verb, resource, and output format. The description further differentiates the tool by enumerating ~130 source formats including raw camera formats 'that nothing else in this product can open', which sets it apart from sibling file tools like get_onedrive_file or get_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?

Three concrete use cases are given ('turn a client's deck into images you can actually put in an ad... get a usable JPG out of a designer's PSD... hand someone a PDF of a spreadsheet'), giving clear contextual guidance for when to invoke the tool. However, it never explicitly states when NOT to use it or names an alternative sibling for comparison, so exclusions are left to inference.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, but the description adds valuable context beyond those: it switches to the new workspace, isolates data between workspaces, returns the existing workspace on re-run, and clarifies that the research credit cost only applies to draft_brand. 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?

Every sentence earns its place: the main action is front-loaded, followed by isolation semantics, usage routing, idempotence, and cost. It is dense yet well-organized with no filler or redundancy.

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

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

For a creation tool with no output schema, the description covers purpose, switching behavior, isolation, idempotence, and cost thoroughly. The only gap is that it does not state what the tool returns on success beyond the switch, which an agent might need for follow-up calls. Minor gap given the rich context otherwise provided.

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 name and activate already have clear descriptions in the schema. The description's mention of 'switch to it' reinforces the activate parameter's behavior but does not add new meaning beyond what the schema already provides, 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 opens with a specific verb and resource ('Add a NEW brand workspace') and clarifies it is a separate brand/client on the account. It explicitly distinguishes itself from sibling tools draft_brand (fill) and update_brand (edit), so an agent can tell them apart 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?

States exactly when to use it ('for a second brand or a new client') and names alternatives with their purposes ('use draft_brand to FILL a workspace, and update_brand to edit one'). It also flags the idempotent re-run behavior and cost implications, leaving no doubt about appropriate invocation.

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 the tool returns the document id and URL and requires the Google Drive connector. This is useful operational context. It could add more about overwrite/duplicate behavior, but creating a new doc is adequately implied.

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 concise sentences: main purpose with examples, return value, and connection prerequisite. Every sentence earns its place with no redundant restatement of the title or schema.

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

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

For a simple create tool with fully covered parameters, the description provides everything needed: what it creates, example uses, return values, and setup requirement. Even without an output schema, the return info is explicitly stated.

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

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

The input schema already describes both parameters (title and text) at 100% coverage, so the baseline applies. The description adds that text is optional and gives example content types, but does not meaningfully expand on parameter formatting or constraints.

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 ('Create'), a specific resource ('a new Google Doc in the user's Drive'), and a clear scope (title + optional body text). This clearly differentiates it from create_sheet, create_drive_folder, append_to_doc, and update_doc.

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 concrete example use cases (export ad copy, creative brief, report) and states the prerequisite that Google Drive must be connected. It does not explicitly mention when to prefer a sibling like append_to_doc or update_doc, but the usage context is clear.

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

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

Annotations already 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?

Beyond the annotations (which already indicate a non-read-only operation), it discloses the optional fill behavior, the row-array layout including header treatment, the returned spreadsheet id + URL, and the Drive connector requirement. 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?

Four tight sentences that front-load the core behavior, then add only the needed formatting, return, and connection details. 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 simple 2-parameter tool with no output schema, the description covers return value, row format, and auth prerequisite. It is slightly incomplete only in not naming the sibling tools for appending/updating an existing sheet.

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 rows and title are already described in the schema; the description mostly restates 'array of row arrays, first row = headers' in natural language. It adds little information that an agent couldn't already derive from 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 action ('Create'), an exact resource ('new Google Spreadsheet in the user's Drive'), and gives concrete example payloads ('swipefile, ad list, performance report'). Saying 'new' plus 'Spreadsheet' separates it from create_doc and from update/append sheet 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?

Gives clear contexts for use: creating a fresh spreadsheet and optionally exporting row data, and a concrete prerequisite ('Needs Google Drive connected'). It doesn't explicitly say when to prefer append_to_sheet or update_sheet instead, so it misses the explicit exclusions needed for 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 flag destructiveHint:true and readOnlyHint:false; the description substantially supplements them by disclosing irreversibility, impact on everyone the workspace is shared with, connected-account disconnection, the dry-run inventory behavior of the first call, and the rationale that confirming intent does not prove the correct workspace was picked. No contradiction with 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 long, but every sentence carries safety-critical weight and the most urgent facts (permanent, everything, irreversible, shared impact) are front-loaded. The rationale sentence about wrong targets is slightly verbose but earns its place for a destructive tool of this severity.

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 fully specifies the call workflow, the confirmation requirements, and the anchor-brand exclusion. The only minor gap is not describing the exact format of the inventory the first call returns, though the instruction to show it verbatim reduces the need for that detail.

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 above it by explaining why confirmName and confirmConnectors exist (protecting against destroying a live brand) and how they derive from the first call's reported inventory. It connects the parameters into a workflow even though it doesn't reformat each parameter's syntax.

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 — 'PERMANENTLY delete a brand workspace and EVERYTHING in it' — and enumerates the full contents (brand profile, memory, swipefile, Library creations, generated assets, avatars, skills, playbooks, chats) plus disconnection of connected accounts. This clearly distinguishes it from siblings that delete narrower resources (delete_playbook, delete_skill, delete_drive_file) or mutate brands (update_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?

Provides an explicit two-phase protocol: call without confirm first to obtain an inventory, show it verbatim, get an unambiguous yes, then call again with confirm:true plus the exact confirmName and confirmConnectors values. It also names the when-not-to case — the account's first/anchor brand cannot be deleted this way and must be replaced from the app.

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 valuable behavioral detail beyond the annotations: it records a cross-device delete to prevent reappearance, it only removes the roster entry rather than affecting ads, and it clarifies no confirmation is needed because the creator can be saved again. This fully explains the destructive-but-reversible nature of the 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 tightly packed sentences lead with the core action, then clarify scope, side effects, and re-creation path. No filler, and each sentence adds 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?

For a single-parameter tool with rich annotations and no output schema, this description is complete. It tells the agent what the tool affects, what it does not affect, how the id is obtained, and how the action can be reversed. Nothing essential is missing.

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

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

Schema description coverage is 100%, and the schema already documents the 'id' parameter as 'the creator id (from list_creators)'. The description reiterates this source but does not add new parameter-level detail, 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 ('Remove'), a specific resource ('a saved creator from this workspace's cast'), and an explicit identifier source ('by id (from list_creators)'). It clearly distinguishes this tool from sibling tools like save_creator and 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?

The description gives clear context for when to use the tool: removing a creator from the workspace cast by id. It also explicitly tells the agent what this tool does NOT do (ads already rendered are untouched) and names save_creator as the way to re-add the same portrait, effectively covering alternatives and exclusions.

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

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

Annotations already 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?

Beyond the annotations (destructiveHint=true, idempotentHint=true), the description adds valuable behavioral detail: leads are unaffected and remain readable, only the webhook delivery stops, and state is read back from LinkedIn. It also mentions 'Free,' which is useful operational context. 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 short sentences deliver the action, the source of the ID, the exact scope of destruction, and the source-of-truth behavior. There is no redundant or filler content, and the most important operational detail 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?

For a simple three-parameter destructive tool, the description covers the critical context: what is removed, what is not removed, and where the ID comes from. It does not describe the return value or how to reverse the action, but the annotations and schema cover the rest, making this adequate though not exhaustive.

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 required parameter subscriptionId lacks a schema description, but the tool description fills that gap by pointing to list_linkedin_lead_subscriptions as the source. The optional pageId and adAccountId are already described in the input schema, so between the description and schema, all parameters have meaningful semantics.

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

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

The description states a specific action ('Remove') on a specific resource ('lead notification webhook') and clearly distinguishes it from lead deletion: 'Leads themselves are unaffected and stay readable; only the real-time delivery stops.' It also names the source of the identifier, which removes ambiguity from similarly named LinkedIn lead 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 clear context: use the subscriptionId from list_linkedin_lead_subscriptions, and the effect is only on real-time delivery. It does not explicitly name an alternative action such as subscribe_linkedin_leads or list_linkedin_lead_subscriptions, but the context is strong enough for an agent to know 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?

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?

Beyond the annotations (destructiveHint=true, idempotentHint=true), the description discloses a non-obvious trait: 'Records a cross-device delete so it does not come back on the next sync,' which an agent could not infer from structured data. The 'Minor + re-creatable' note adds severity context that helps the agent set confirmation expectations. No contradiction with 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?

Three short sentences: the core action is front-loaded, followed by the sync behavior and the severity rationale. Every sentence adds information; there is no filler.

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

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

For a one-parameter destructive tool with a fully documented schema and a complete annotation set (destructive, idempotent, read-only), the description covers action, id source, persistence behavior, and severity. Return-value details are reasonably unnecessary given no output schema and the simple action.

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%; the schema already documents id as 'the playbook id (from list_playbooks)'. The description repeats the same provenance rather than adding new parameter details, 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 names a specific verb ('Delete'), a specific resource ('saved playbook'), and the source of the identifier ('from list_playbooks'). This clearly differentiates delete_playbook from its delete_* siblings such as delete_brand, delete_drive_file, and delete_skill.

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 clear operational context: the id must come from list_playbooks, pointing the agent at the prerequisite call. It also justifies invocation without extra safeguards ('Minor + re-creatable, so no confirm needed'). It stops short of explicitly naming alternatives or when-not-to-use scenarios.

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 destructiveHint=true and idempotentHint=true. The description adds meaningful behavioral context: only custom skills are affected, built-in skills are protected, and the skill is minor and re-creatable, which is why no confirmation is needed. This goes beyond the structured hints without contradicting 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 sentences with no filler. The core action and scope come first, the exclusion rule follows, and the final sentence provides useful operational context. 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 single-parameter delete tool, the description covers what can be deleted, what cannot, where to get the id, and why no confirmation is needed. Annotations cover safety and idempotency, so nothing essential is missing.

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

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

Schema coverage is 100%, and the id property is already described as 'the custom skill id (from list_skills)'. The description repeats this same information rather than adding new parameter-level meaning, so the baseline 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 ('Delete') and a clear resource ('one of the workspace’s CUSTOM skills'), scoped by id and sourced from list_skills. It also distinguishes this tool from related skill tools like get_skill, save_skill, and list_skills by emphasizing custom-only deletion.

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 when deletion is allowed (custom skills) and when it is not (built-in skills/recipes can’t be deleted). It also tells the agent where to obtain the id (from list_skills), which is practical routing guidance for use.

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 read-only/non-destructive; the description adds substantial behavioral detail: four refusal conditions, the inability to see conversions for organic posts, the requirement to print summary verbatim, and the attribution of fallback baselines. These go well beyond the annotations and materially shape how an agent interprets results.

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

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

The description is long and heavily formatted, but each block carries diagnostic heuristics, routing, or refusal logic that would otherwise be absent. It is front-loaded with the core purpose, though the all-caps style and several run-on passages keep it from being maximally clean.

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

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

For a complex diagnostic tool with no output schema, the description covers selection, invocation, edge cases, refusal behavior, fallback attribution, conversion limitations, and the required summary output. An agent has enough context to call and interpret the tool correctly without inventing missing details.

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 per the rubric the baseline is 3. The description mainly reinforces converting:false behavior already documented in the schema, and it does not add new parameter-level meaning beyond what the input schema already gives for limit, channel, and converting.

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 diagnostic function: it tells what is wrong with a given post and where the next edit goes, and explicitly contrasts with sibling post_performance (which hook is ahead vs what is wrong). This makes the tool's unique role 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?

Gives explicit routing guidance: use post_performance to see which hook is ahead, use diagnose_posts to identify hook/retention/offer problems, and follow with mine_angles/list_hooks/plan_variations. It also defines when NOT to diagnose (posts younger than ~24h, unreliable metrics, fewer than 5 baseline posts) and when converting:false should be passed.

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

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

Annotations already mark this destructive and non-read-only, but the description goes well beyond them: credentials are always dropped, provider tools stop immediately, published posts are unaffected, revocation at the provider varies (Threads/Microsoft lack endpoints), and the unconfirmed call reports the revokesAtProvider status. This is exactly the behavioral context an agent needs for a destructive, irreversible action.

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

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

The description is long but every sentence earns its place for a destructive irreversible operation, and the most critical facts (credential drop, published posts unaffected, browser-only reconnection) are front-loaded. The heavy use of ALL-CAPS emphasis is stylistically noisy but does improve skimmability for an agent.

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 explaining what the unconfirmed call reports and how to relay it. It covers consequences, provider-dependent variance, preconditions, irreversibility, and cross-references to sibling tools — nothing an agent needs to call this safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3 with the schema carrying the parameter documentation. The description adds minor reinforcement — that confirm:true is mandatory and that provider ids come from list_connectors — but does not substantially extend what the schema already states about each 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 opens with a specific verb+resource ('Disconnect a third-party account from this workspace') and enumerates the affected providers, making the tool's scope unambiguous. It also distinguishes itself from related siblings like list_connectors and list_connector_accounts by positioning them as precursors rather than the action itself.

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 call sequencing: name the provider to the user first, then call with confirm:true, and relay the revocation result verbatim. It names list_connectors as the source for exact provider ids and warns that an agent cannot undo the action because reconnecting needs a browser, effectively stating when not to proceed.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses important behaviors: it costs 0 credits, a domain can resolve to a different company, the tool cannot ask the user for clarification, and the caller owns the verification check. This materially changes how an agent should invoke and validate the tool.

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

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

The description is dense but every sentence earns its place: purpose first, then cost, then a clearly marked IMPORTANT warning with an example and an actionable rule. It avoids repeating schema details and is structured for quick parsing by an agent.

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, it covers the returned object shape ({name, products, logo, …}), the fields to verify, and the save behavior. It could be more explicit that exactly one input source is expected, but the alternatives are clearly stated.

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 extra semantic guidance: it maps the three input modes to parameters, warns about domain ambiguity with a concrete example, and explicitly recommends save:false until the result is confirmed. That goes beyond the schema field descriptions.

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

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

The description opens with a specific verb ('onboard') and resource ('brand profile'), lists three input sources, and names the downstream consumers (plan_ad / generate). It is clearly distinct from generic brand management tools, though it does not explicitly contrast itself with sibling create_brand/update_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?

It clearly states when to use the tool: to turn a domain, description, or social handle into a reusable brand object. It also gives strong operational guidance—verify the returned name, re-draft if wrong, and pass save:false until confirmed—but does not explicitly name alternatives or say 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?

The description richly discloses behavior beyond the sparse annotations: it explains the full pipeline (transcribe, translate, re-voice, lip-sync), notes the output is a served URL, and states the operation is paid. It also clarifies that the original footage is not re-rendered, which is significant 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?

The description is compact and front-loaded: the core value proposition appears first, followed by usage instructions, payment detail, and return type. Every sentence contributes new information without unnecessary fluff.

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

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

Given there is no output schema, the description appropriately mentions the return value (served URL) and cost (paid). It also covers the main input requirements and the optional script override. It could be slightly more complete by mentioning billing setup or prerequisites, but for this complexity level it is largely sufficient.

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 adds a small amount of parameter guidance—'Just pass the video and the language' and 'pass script only to override'—but the input schema already documents these same semantics, so the added value is marginal.

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

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

The description clearly states the verb 'localize' with the resource 'a finished video' and highlights the key distinction from re-rendering: the visual, timing, and edit remain untouched. This makes it easy to tell apart from siblings like edit_video, clip_video, or reframe_video.

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

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

It gives clear context on when to use the tool: pass the video and target language, and only override the script when the auto-transcript is wrong. It doesn't explicitly name alternatives or state when not to use it, but the 'finished video' + 'no re-render' framing conveys the appropriate use case.

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

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

The description goes beyond the sparse annotations by disclosing that the copy is independent, never affects the original, and is a genuinely new post that will publish even where the original already did. These are exactly the non-obvious behaviors an agent needs to know, and 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?

The description is substantial but every sentence carries distinct information: purpose, use cases, copying/override behavior, new post independence, and the retry alternative. It is front-loaded with the core operation and uses formatting like INDEPENDENT and NEW to emphasize key facts without 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 tool with 18 parameters, nested objects, and no output schema, the description covers the essential invocation semantics well: required source id, scheduling options, override behavior, and relationship to retry_scheduled. The only small gap is that return values are not mentioned, but this does not block correct selection or 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 72%, so the schema already documents most parameters. The description adds valuable meaning for the key scheduling choices ('Give a new time in at, or useQueue:true') and clarifies that any copied field can be overridden in the same call. A few schema-undocumented parameters like link and imageUrl remain implicit, but the core semantics are well covered.

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: copying an existing scheduled or already-published post into a NEW queued post. It clearly distinguishes itself from the sibling retry_scheduled, so an agent can tell them apart immediately.

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

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

It gives the concrete scenarios for using this tool (reuse a post, run a creative again, re-send after publishing) and explicitly says to use retry_scheduled instead when only failed channels need to be re-fired. This is clear when-to-use and when-not-to-use guidance.

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

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

Annotations only set readOnlyHint=false, openWorldHint=false, idempotentHint=false, destructiveHint=false. The description adds meaningful behavior: it preserves original motion/timing/edit, changes subject/setting/style; it is a paid render; and it returns the served URL of the edited clip. It also discloses the identity/product grounding behavior via the `elements` parameter. A small gap: it doesn't explicitly warn about whether the source clip is consumed or what happens to the audio if keepAudio is omitted, but the schema covers keepAudio default. The behavior about preserving motion/timing is important and disclosed.

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

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

The description is dense but well-structured: the first sentence states the core transformation, followed by concrete examples, constraints, exclusions, and cost/return. It is longer than ideal, but every sentence adds value, and key behavioral information is front-loaded. The NOT list is long yet necessary for routing among many video sibling tools.

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 complexity (video-to-video transformation with optional grounding, audio toggle, paid render) and no output schema, the description covers the core semantics: what it does, constraints, alternatives, and return type (served URL). It doesn't detail failure modes (e.g., what if the video is too long or the instruction is ambiguous) or how the audio is handled when keepAudio is false in terms of output format, but given annotations and schema coverage, this is adequate and only missing minor edge-case guidance.

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 adds meaningful semantics beyond the schema: it explains the `elements` parameter's purpose ('so the edit restores the REAL thing instead of re-inventing it') and that `instruction` is in the user's own words, mapping to the natural-language behavior. It also adds context about the video source URL, tying it to 'a previous render, a job result, or list_library' – but that comes from the schema. The description reinforces the exact role of `instruction` and `elements` without redundancy, 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?

The description clearly states a specific verb and resource ('EDIT/transform an existing video clip with a natural-language instruction (video-to-video)'), and explicitly distinguishes itself from sibling tools like post_edit, generate_video, dub_video, recast_motion, and render_ad via concrete examples. The transformation scope is well-defined, including what it does NOT do, which makes it immediately distinguishable from related 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 provides explicit when-to-use guidance ('Use for...') with multiple concrete examples, and explicit when-not-to-use exclusions naming specific sibling tools (post_edit, generate_video/render_ad, dub_video, recast_motion). It also gives a practical constraint ('Best on 3–10s clips'), making it easy 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?

Adds significant behavioral context beyond annotations: it discloses that hosts that re-read the tool list will show new tools, while connect-time hosts like ChatGPT will not, and that the tool reports this instead of returning a misleading success. It also states it is free, instant, and never turns anything off, which is not evident from the annotations alone.

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

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

The description is long, but nearly every sentence carries actionable information: trigger conditions, host caveat, default roster, held-out groups, and accepted values. It is front-loaded with the core action and expands only where it directly affects 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 meta-configuration tool with no output schema and one parameter, the description is complete: it lists valid groups, explains the default and excluded groups, provides concrete trigger examples, covers the host-dependent limitation, and gives the fallback connection-time route. No meaningful gap remains 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?

Though the schema already documents the single 'groups' parameter, the description enriches it with the full list of accepted groups ('core, research, create, channels, channel_admin, analytics, ads, files, workspace — or all'), the default roster, and the held-out groups. This gives an agent everything needed to construct correct calls.

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 ('Switch on a group of tools') and clearly distinguishes itself from the fixed roster and other tools by explaining it affects the session's tool list. The contrast with the `?tools=all` connect-time route helps an agent understand exactly what this tool is for.

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 instructions: 'CALL THIS THE MOMENT YOU NEED ONE' with concrete examples for ads and analytics. It also names the alternative ('?tools=all') for hosts that fix their roster at connect time, and explains when that route should be preferred.

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 provide readOnlyHint=true and destructiveHint=false. The description adds valuable context: '0 credits' (cost), 'redacted occurrences' (privacy behavior), and 'shape-only echo of the inputs' (no raw sensitive data returned). These go beyond the annotations and set accurate expectations for a read-only 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 sentences, tightly packed. The first sentence front-loads the purpose and contents; the second sentence adds the value proposition. No redundant phrases or filler.

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

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

For a one-parameter, read-only lookup with no output schema, the description fully covers what data is returned, where the fingerprint comes from, safety (read-only, 0 credits), and the purpose (bug reproducibility). Nothing essential is missing.

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

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

Schema coverage is 100% and clearly documents fingerprint as 'the fp value from list_errors.' The description reinforces this by saying 'by fingerprint (from list_errors)' but does not add new semantic meaning beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource: 'One error group in full by fingerprint.' It clearly names the source (list_errors), specifies what is returned (every field, redacted occurrences, status, connector, job id, workspace, shape-only inputs), and distinguishes itself from list_errors by focusing on a single group in full detail.

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 clearly implies a workflow: start with list_errors to get a fingerprint, then call error_detail for the full error group details. It explains why you would use it ('This is what makes a bug reproducible') but does not explicitly list exclusions or compare against alternatives like get_job or list_errors.

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 non-obvious behavior beyond annotations: every call creates a brand-new deck, the drive.file scope limits access to files Hermoso created, expired Meta ad-library links degrade gracefully to a text placeholder, and the reply reports how many such cases occurred. These details align with the annotations (not read-only, not idempotent).

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

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

The main capability is front-loaded in the first sentence, and subsequent sentences add important constraints, failure modes, and prerequisites. It is somewhat dense and includes minor product framing, but each statement 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 mutating tool with no output schema, the description covers the output format (presentation id + URL), side-effect semantics, failure handling, permissions, and integration prerequisites. Nothing essential for correctly calling and interpreting the tool is missing.

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

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

Schema description coverage is 100%, so the schema already documents limit, title, and collection. The tool description does not add parameter-level meaning, but it doesn't need to; the baseline of 3 applies because the schema carries that 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 and resource: turn a swipefile collection into a Google Slides deck with one slide per saved ad, including creative, brand, copy, run dates, and platform. This clearly distinguishes it from generic document/sheet tools and from the prior JSON-only export path.

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 frames the intended use case ('the thing a marketer actually presents to a client or a team'), states the Google Drive prerequisite, and warns that it cannot add slides to an existing user-owned deck. It does not name a sibling tool as an explicit alternative, so it stops short of a full when-not-to-use statement.

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

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

Discloses key behavioral traits beyond annotations: it is keyless/free, requires a confident match, returns 0 and saves nothing on ambiguity, saves screens with durable URLs, and makes them immediately usable. These details go well beyond the annotation flags and give the agent an accurate model of execution and failure.

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

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

Four sentences, each dense with useful information, and the core purpose is front-loaded. There is slight redundancy around the screens being saved and usable, and the emphatic 'REAL' adds tone but no fact, so it is not a perfect 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 two-parameter tool with no output schema, the description covers defaults, side effects, failure behavior, auth/cost, persistence, and immediate usability. It even implies what a result looks like ('returns 0 screens') sufficiently for an agent to 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?

The input schema already documents both parameters at 100% coverage, including appName's default and brandId's fallback to the active brand. The description mostly restates the appName default without adding deeper semantic value, 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?

States the specific verb 'Pull... App Store screenshots into the workspace brand' with both the resource (App Store) and the side effect (saving into the brand). It names the intended downstream use (make_template_ad(template:'app-ui-tour')), which clearly distinguishes it from generic fetch or list tools in the sibling set.

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

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

Explicitly gives trigger conditions: use when the brand has 0–1 app screens on file, when the user asks to 'pull my app's screenshots', or for a specific template. It also tells the agent not to retry with guesses and to relay a zero-result outcome plainly, making when-to-use and when-not-to-use clear.

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

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

Annotations already mark this as read-only and non-destructive, and the description adds useful behavior beyond that by specifying the return shape (absolute URL and download URL) and accepted input forms (/generated/ path or any URL). It does not cover error behavior or authentication, but the safety profile is covered by 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 entire description is one concise sentence that front-loads the primary purpose and includes the most important input and output details. There is no wasted text or redundant restatement of the title.

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 tool with read-only annotations and no output schema, this description is complete. It explains what the tool takes, what it returns, and the kind of inputs it handles. No critical information is missing for an agent 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 schema already documents the url and name parameters. The description adds marginal context by clarifying 'any URL' is accepted, but does not meaningfully expand on the parameter meanings beyond what the schema provides. The baseline 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 uses a specific verb ('Resolve') and identifies the exact resource ('generated asset reference') and output ('clickable absolute URL + a direct download URL'). It clearly distinguishes this tool from siblings like upload_file or store_get by focusing on URL resolution rather than storage or 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?

The description clearly implies when to use the tool: whenever a generated asset reference or URL needs to be converted into clickable and downloadable URLs. It does not explicitly name alternatives or exclusions, but the context is strong enough that an agent can recognize the correct use case.

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

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

Annotations already convey readOnlyHint=true and destructiveHint=false; the description adds meaningful behavioral context beyond that: allowlist enforcement via path, raw provider JSON output that is 'large and messy', and credit consumption. This gives the agent a strong sense of cost and output quality before invocation. No annotation contradiction.

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 escape-hatch concept and example, then logically flows into platform list, parameter conventions, and warnings. The platform list is long but necessary for a generic tool. Every sentence carries useful information, though the density is slightly high and could be tightened.

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

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

For a generic fallback tool with no output schema, the description covers the key operational facts: allowed platforms, parameter naming patterns, allowlist restriction, raw/voluminous output, and credit cost. A minor gap is lack of explicit mention of authentication or rate limits, but annotations and the given details are 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 coverage is 100%, but the description adds semantic depth beyond the schema: it explains that param names vary per endpoint ('profiles use handle, keyword searches use query, Reddit uses subreddit') and clarifies that path must be an exact allowlisted endpoint. This materially improves an agent's ability to construct valid invocations.

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 role: 'Generic escape hatch for any ALLOWLISTED long-tail social/web endpoint the dedicated search_* tools don't cover.' This is a clear verb+resource+scope and explicitly distinguishes it from the search_* siblings. Concrete examples like '{path:'/v1/instagram/profile', params:{handle:'nike'}}' further anchor 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?

Usage guidance is explicit and actionable: use this only when 'dedicated search_* tools don't cover' an endpoint, and 'prefer the dedicated search_* tools' as the safer alternative. The WARNING about raw JSON and 'Spends credits' also adds cost/risk considerations that help an agent decide when this tool is appropriate.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds valuable behavioral context: results are 'grounded by web search', the tool costs '0 credits', and the default mode excludes the searched company. This goes beyond the annotations by clarifying the nature of the results and cost implications.

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

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

A single, dense sentence front-loads the core purpose, then efficiently covers the three modes and the zero-credit cost. There is no filler or redundancy, and every clause contributes useful information.

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

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

For a simple two-parameter, read-only discovery tool, the description covers purpose, modes, default behavior, search grounding, and cost. The absence of an output schema means the description could mention the return shape in more detail, but 'Discover... brands' and the mode descriptions make the expected result reasonably clear.

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 'domain' and 'mode' are already documented within the input schema. The description largely restates the mode semantics rather than adding new parameter-level meaning, though it does clarify the default mode and the exclusion behavior in a more agent-readable 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 uses a specific verb ('Discover') and a clear resource ('a brand's competitor / similar / adjacent brands from its domain'), making the tool's purpose immediately identifiable. It also disambiguates itself from sibling tools like competitor_teardown and pull_competitor_ads by focusing on brand discovery rather than teardown 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?

The description gives clear context: the tool discovers brands related to a given domain, with explicit mode options and defaults ('mode=competitors (default...)', 'inspiration...', 'company'). It does not explicitly name alternatives or state when not to use it, but the mode breakdown provides enough operational guidance for an agent to select appropriate calls.

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

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

Annotations already mark it as read-only and non-destructive, and the description adds substantial behavioral context: credit costs per search and enrichment, free repeats within 20 minutes, default platform/query counts, ranking logic, and the inclusion of public contact info. This goes well beyond the structured fields.

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

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

The description is front-loaded with the core purpose and remains dense and information-rich throughout. It packs ranking, enrichment, cost, use cases, and downstream actions into one paragraph, though the long sentence structure could be slightly easier to parse.

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 7 parameters, no output schema, and multi-platform behavior, the description covers the essential operational details: what is returned, how results are ranked, cost model, default behaviors, and example use cases. Nothing critical is missing for an agent to select and 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 high at 86%, and the description adds meaningful context beyond the schema, including credit implications, defaults (3×3, top 6 enrichment), and what 'queries' means. However, minAvgViews has no schema description and is also not explained in the description, leaving one gap in parameter understanding.

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 ('Scan'), exact resources (organic TikTok, Instagram Reels, YouTube), and a clear transformation pipeline: posts are folded into creators, ranked on median views, engagement rate, and niche frequency. It also distinguishes itself from related search tools by emphasizing creator-level aggregation and contact enrichment, not raw post search.

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 names use cases — influencer sourcing, UGC casting, and partnership prospecting — with an illustrative question ('who should we send product to?'). It also shows downstream next steps (shortlist, check profile, draft outreach, approve for Partnership Ads), though it does not explicitly define when NOT to use this tool versus raw search siblings.

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

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

Annotations already mark read-only/idempotent/non-destructive, and the description adds cost (free), scope (includes ads, analytics, channel_admin groups omitted from session list), and output format (parameters in one line). This gives behavior beyond structured annotations without contradicting 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?

The description is compact and front-loaded with the scope and trigger. It is slightly dense with parentheticals and repeats read-only from annotations, but every sentence contributes actionable guidance.

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

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

For a discovery tool with no output schema, it explains why tools may be missing, when to call, what the result contains, and the follow-up action. Nothing essential is missing 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?

Input schema provides 100% description coverage for query, group, and limit, so the baseline applies. The description echoes the idea of searching by name/task/group but adds no parameter-level detail beyond what the schema already offers.

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?

Defines a specific verb and resource: search every Hermoso tool by name, task, or group and return parameters in one line. It also distinguishes itself by explaining scope beyond the session list, so an agent knows exactly what it 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?

Provides explicit trigger conditions: use whenever the user asks for something with no visible tool, listing campaign, ad set, lead form, report, keywords, audiences as examples. It also prevents false negatives by stating that a missing tool is never proof the feature is missing and gives the next step (call_tool).

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

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

Annotations only say readOnly=false and destructive=false, so the description adds crucial behavioral detail: it is non-destructive because 'the original is untouched' and it 'Returns a NEW video.' It also discloses performance and cost characteristics (~30s, a couple of credits) and clarifies it uses no AI model, which meaningfully shapes agent expectations. 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?

The description is dense but well-organized: core purpose up front, then pill behavior, then grain behavior, then a clear non-destructive return guarantee. Almost every clause delivers actionable information—constraints, defaults, mode combinations, and cost—without fluff. It earns its length.

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

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

For a 7-parameter tool with no output schema, the description covers inputs, conditional requirements, behavior, and return type well. It specifies the input is a served mp4 URL from a previous render/job, explains what a NEW video means, and documents the main mode interactions. It could be slightly more explicit about what happens to pill-related parameters when pills=false, but the schema and description together make this reasonably inferable.

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 semantic value beyond the schema: it explains the relationship between pills and grain, gives character limits in prose, states copy quality guidance ('concrete real benefits, never fabricated stats'), and clarifies that header is required when pills is on. This goes beyond simply repeating property names and 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 specific action—post-process an EXISTING rendered video—and names the two concrete finishing modes: reviewer-style proof pills and film grain. The phrase 'no AI model' and 'existing rendered video' clearly distinguishes it from generation and broader editing siblings. This is a specific verb+resource definition, not a tautology.

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 clear when-to-use context: apply it to an already-rendered served mp4 to add social-proof pills and/or an anti-AI grain pass. It also explains mode combinations, such as setting pills=false for a grain-only pass. However, it does not explicitly name sibling tools like edit_video, clip_video, or upscale_video or state when to prefer them instead, so it stops short of full alternative routing.

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

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

Although annotations only tell us readOnlyHint=false, destructiveHint=false, idempotentHint=false, the description clearly discloses the surprising behavior: video track is replaced while the rest of the video and ALL audio stay byte-identical. It also surfaces the billing consequence ('bills only the replacement clip's seconds (~1/3 of a full render)') and the lip-sync hazard. 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 dense sentences, each earning its place: behavior, when-to-use plus cost, and a critical do-not rule. The most important behavioral constraint is front-loaded ('VIDEO TRACK ONLY'), and the sibling-differentiating angle comes immediately. 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 complex surgical video-editing operation with no output schema, this description covers the key preconditions, constraints, side effects (audio preservation), billing model, and the one dangerous exclusion (speech overlap). The six parameters are all documented in the schema and the description maps them to behavioral context. Nothing critical is missing for an agent deciding to call it and pick a window.

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 a baseline of 3 applies. The description adds meaningful semantics beyond the schemas: it defines the window constraint (1.5-8s), the enforcement rule for speechWindows, and the billing implication of choosing a smaller window. It doesn't detail the exact format of refImage or prompt beyond 'what the replacement footage should show', but parameter semantics are largely carried by 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 ('surgically re-render ONE time window... and splice it back'), a specific resource (existing rendered video, VIDEO TRACK ONLY), and a precise scope. Differentiates itself from full re-render and from video siblings like clip_video or edit_video by describing the surgical splice behavior.

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

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

Explicitly says when to use this tool ('when one beat/shot is broken... and a full re-render would waste the parts that worked'), what it bills, and gives a hard exclusion ('Do NOT pick a window covering spoken dialogue') with the mechanism to enforce it (pass speechWindows). This goes beyond any sibling definition.

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 destructiveHint and idempotentHint annotations, the description adds meaningful behavioral detail: it records a cross-device delete, prevents the memory from coming back, and notes that the operation is minor and re-creatable, so no confirmation is needed. This gives the agent a strong safety and side-effect picture.

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-loaded: the primary action is stated first, followed by the most important behavioral implications and a rationale for not requiring confirmation. Every sentence contributes useful information with no redundancy.

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

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

The description is complete for a single-parameter destructive tool: it identifies the target, the id source, the cross-device effect, durability of the deletion, and the re-creatable nature. Given the rich annotations and simple schema, nothing essential is missing.

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

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

The input schema already fully documents the sole parameter 'id' as 'the memory item id (from list_memory)', so schema coverage is 100%. The description repeats this source but adds no new parameter-level meaning, which aligns with the baseline score for high schema coverage.

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

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

The description clearly states the verb 'Delete' and the resource 'saved Memory item', and specifies the identifier source ('by its id (from list_memory)'). This unambiguously distinguishes it from generic delete tools and related memory tools like remember and list_memory.

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 makes clear this tool is for deleting a specific saved memory using the id obtained from list_memory. It gives enough context for when to use it, though it does not explicitly mention alternative memory tools like tidy_memory or remember for comparison.

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 meaningful behavior beyond the annotations: it states that no cell values are changed, that the tool is never gated, and that defaults apply all three formatting actions to the first tab. It also explains how to skip individual steps with freezeRows:0, boldHeader:false, and autoResize:false. This is consistent with the idempotentHint and destructiveHint 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 information-dense and front-loads the core purpose with three clear actions. It then adds workflow context and parameter-level skip behavior in compact, scannable prose. Every sentence contributes operational value, and there is no redundant restating of the title or schema.

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

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

The description provides the canonical workflow, default behavior, skip flags, and a safety profile, which is strong for a low-complexity formatting tool. It is incomplete only in not addressing how to target the spreadsheet via sheetUrl or spreadsheetId, and there is no return-value note, though that is less critical for an action-style tool.

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

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

Schema description coverage is only 33%, so the description must compensate. It does add semantics for autoResize and boldHeader by tying them to visible effects, and it clarifies freezeRows:0 and the default-first-tab behavior. However, sheetUrl and spreadsheetId are never explained in either the schema or the description, leaving a notable gap for how the target spreadsheet is identified.

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 ('Make ... readable') and enumerates three concrete formatting actions: bolding the header row, freezing it, and auto-sizing columns. It also names the resource (an exported Google Sheet) and positions the tool right after create_sheet, which differentiates it from other sheet-related siblings.

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

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

The description explicitly says 'Worth calling right after create_sheet,' giving a clear trigger and workflow context. It also notes that the tool 'changes no cell VALUE' and is 'never gated', which tells an agent when it is safe and appropriate to call. It does not enumerate alternative tools for value edits, but the provided guidance is sufficient for the common workflow.

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 three important behaviors: blocking with a 1–3 min wait, capability gating (canAvatar in hermoso_capabilities), and credit consumption. This goes well beyond the false readOnly/idempotent/destructive hints. It does not describe the return artifact, though no output schema is provided.

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 carries distinct value: what it does, how long it blocks, and what prerequisites/costs apply. No redundant filler; the core action 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?

Given the schema covers all parameters and annotations capture mutation/idempotency hints, the description supplies the missing operational context: duration, capability requirement, and credits. It leaves out what the tool returns or where the clip is saved, but the other essential context is complete enough for an agent 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 schema already explains image, script, voice, and resolution. The description adds no new parameter-level meaning beyond hinting the image should be a portrait, so baseline 3 is appropriate.

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

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

The description uses a specific verb/resource: 'Render a TALKING-AVATAR / creator lip-sync clip from a portrait image + a script.' This clearly differentiates it from siblings like generate_video, generate_voice, or make_explainer by naming the unique output type and inputs.

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 communicates when to invoke: when the user needs a talking-avatar/lip-sync clip from a portrait and script. It also gives prerequisites ('Requires the avatar capability...') and cost/duration context. It does not explicitly name alternatives or exclusions, so it is not a 5.

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

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

Annotations carry no safety profile (all hints false/absent), so the description bears the full burden and delivers: it discloses credit spend, fast latency, that saved-brand hydration decides the engine, that a named model is only honored without references, and that raw:true reaches the provider byte-identical with no rewriting. No contradiction with annotations exists—'Spends credits' is consistent with readOnlyHint:false.

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

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

The purpose is front-loaded and the content is organized into labeled sections, but the engine-routing guidance is effectively stated twice ('pass raw:true (or useBrand:false) to render on exactly the model you asked for' followed by the RAW MODEL ACCESS paragraph), and the ALL-CAPS headings add noise. The density is justified by real pitfalls, but trimming would improve readability.

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

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

With no output schema, the description correctly covers the return value ('served URL'), durable delivery, per-model validation, and credit spending—the essentials for invoking correctly. Given the tool's high complexity (7 params, brand-hydration traps), coverage is strong; it is only light on failure modes and exact credit cost, which are likely covered by companion billing 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 adds genuine value beyond the schema by explaining cross-parameter interactions the schema's per-field text does not: the refImages/useBrand/model/raw interplay, the wrong-brand compositing pitfall, and how engine routing is decided by brand hydration. aspectRatio and imageSize get no extra explanation, but the schema already covers them.

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

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

The opening sentence 'Render a finished ad IMAGE and return its served URL' states a specific verb, resource, and outcome, clearly separating it from generate_video, generate_text, and generate_avatar. However, it does not differentiate from the close sibling render_ad, so an agent must infer the boundary rather than have it stated.

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

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

Provides strong condition-based guidance: when to pass refImages, when to switch to useBrand:false (working a non-saved draft_brand), and when to use raw:true. The multi-brand caution and engine-routing note give concrete decision rules. It stops short of explicitly naming tool-level alternatives or exclusion criteria versus siblings like render_ad or make_template_ad.

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 set hint flags to false, so the description carries the behavioral burden. It discloses that a house copywriter system prompt is applied by default, that raw:true strips it entirely, that the default model is the Claude orchestrator, and that the tool is paid by length. The only minor omission is mention of what the return value looks like.

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

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

Dense but economical: it covers the catalog, use cases, sibling differentiation, default behavior, raw toggle, model default, and cost without fluff. The structure uses parentheticals and arrows effectively. It is slightly long, 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?

For a three-parameter tool with no output schema and minimal annotations, the description covers selection criteria, behavioral defaults, cost, and alternatives. The only gap is the implicit, not explicit, return shape — the generated text — which is easily inferable from the tool name and purpose.

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 all three parameters already described, so the baseline is 3. The description adds value beyond the schema by clarifying the default model ('omit for the default Claude orchestrator'), explaining why raw matters, and tying model ids to hermoso_capabilities.

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

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

States a specific verb+resource: 'Text generation against the writing-model catalog' and enumerates concrete use cases (ad copy, hooks, scripts, rewrites, brainstorms). It differentiates from siblings by explicitly routing finished creative to plan_ad → render_ad, and the 'text' scope distinguishes it from image/video/voice generation siblings.

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

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

Gives explicit when-not-to-use: 'no ad assembly (for a finished on-brand creative use plan_ad → render_ad)'. Also provides a concrete condition for raw:true — whenever the ask is not marketing copy. Names the alternatives and the condition that selects them, leaving nothing to inference.

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

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

With annotations carrying almost nothing (readOnly=false, destructive=false), the description carries the full behavioral burden and succeeds. It discloses the automatic music bed and extra charge, prompt rewriting guards, refusal rather than truncation for over-long durations, resolution fallback, 1–3 minute render time, and credit spending—all beyond what annotations provide.

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

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

The description is long but the tool is genuinely complex with 12 parameters, billing implications, model routing caveats, and raw-mode behavior. It is front-loaded with the core purpose and sibling distinction before diving into warnings. Some redundancy with the schema exists, and the heavy use of caps adds noise, but every block adds unique operational guidance.

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

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

Given no output schema, the description still covers the return value (mp4 URL), render duration, cost/credits, audio defaults, raw dispatch behavior, edit-via-refVideo semantics, resolution fallback, and long-clip stitching via plan_ad/render_ad. It is unusually complete for a video-generation tool, leaving little for an agent to guess.

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 decision-making value beyond the schema: it tells agents that durationSeconds must come from hermoso_capabilities and not a generic cap, that naming the model is the only way to reach the longest-clip models, and that audio:false is the only way to decline the charged music bed. That pushes it above 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 opens with a specific verb and resource: 'Render a RAW video clip from your own prompt and return its served mp4 URL.' It explicitly distinguishes itself from render_ad for finished brand ads, so an agent can immediately tell this is the raw/experimental generation path rather than the polished ad pipeline.

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: prefer render_ad for finished brand ads, use this for raw clips or precise manual control. It also explains when to pass refVideo for editing instead of generating, when to name a model, and when to use raw:true, with clear routing intent throughout.

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 are minimal (all hints false), so the description carries the full burden and excels: it reveals refusal behavior for invalid voice names, engines that ignore the voice parameter, that the response reports which voice actually spoke, and the paid cost structure. These are exactly the behavioral traits an agent needs to predict outcomes.

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

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

A single dense paragraph with no filler. The first clause states the core function, the second routes to alternatives, and the remainder unpacks parameter behavior. Every sentence (and most clauses) earns its place.

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

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

With no output schema, the description must convey what the call returns — it does (MP3 URL, actual voice spoken). It also covers required input, default engine, voice selection nuances, cost, and the 900-character limit. 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%, so the baseline is 3. The description adds meaningful extra nuance beyond the schema: the engine-voice dependency, engine defaults, the refusal mechanism, and the pointer to hermoso_capabilities for valid presets. This elevates it above baseline, though the schema already does substantial work.

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

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

The description opens with a precise verb-resource-output statement: 'RAW text-to-speech from the voice-model catalog: speak a script in a chosen voice and return the served MP3 URL.' It then explicitly names sibling tools it is not — render_ad, generate_video, change_voice — making differentiation immediate and 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?

States the exact use case ('standalone voiceover / narration clip') and clearly says 'NOT for adding audio to a video,' then names the three alternatives and what they do. No room for an agent to confuse this with a 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?

Beyond the readOnlyHint and non-destructive annotations, the description adds meaningful behavior: it returns a brand profile plus learned memory, exposes a hasBrand flag, is scoped to the current account/workspace, and costs 0 credits. No hidden side effects are implied.

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 earning its place: what the tool returns, when to call it, and when it is unnecessary. The '0 credits' note is useful and compact, and the guidance 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?

For a zero-parameter, read-only tool with no output schema, the description gives enough context: the agent learns what data is returned, how to interpret hasBrand, what follow-up action to take, and that a prior call is not required for renders. Nothing essential is missing.

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

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

The input schema has zero properties, so there are no parameters requiring explanation. The description correctly avoids inventing parameter details and instead focuses on the output/decision value, which is appropriate for a zero-parameter tool.

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

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

The description identifies a specific resource (the saved brand profile plus learned memory) and a clear purpose: checking whether a brand is on file. It also distinguishes itself from draft_brand and the create tools by explaining this is not a required first step.

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

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

It explicitly states when to call the tool ('when you need to know whether a brand is on file'), what to do based on hasBrand, and when not to call it because create tools read the saved brand themselves. This gives the agent clear routing guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description independently confirms 'Read-only.' It adds value by listing the returned metadata fields, which is especially useful because there is no output schema. It does not cover auth or error behavior, but the read-only safety profile is adequately disclosed.

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

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

Two compact sentences front-load the operation and return fields, then give the required parameter and a safety note. There is no filler or redundant explanation.

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

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

For a one-parameter read-only getter, the description covers what it does, what it returns, where fileId comes from, and that it is safe. Listing the returned fields compensates fully for the absence of 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?

The fileId parameter is 100% documented in the schema as 'the Drive file id (from list_drive_files)', and the description repeats that provenance without adding format, constraints, or validation details. Since schema coverage is high, this meets the baseline but adds little beyond 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?

The description opens with the verb 'Fetch' and the resource 'one Drive file's metadata', then enumerates the exact returned fields (name, type, size, modified time, webViewLink, webContentLink). This clearly distinguishes it from list_drive_files, update_drive_file, delete_drive_file, and get_onedrive_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?

The instruction 'Pass fileId (from list_drive_files)' anchors the intended workflow: first list Drive files, then fetch details for one ID. It does not explicitly name alternative tools or exclusions, but for a single-ID metadata read 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?

Beyond the readOnlyHint and destructiveHint annotations, the description discloses important non-obvious behaviors: renders can take 1–3 minutes, repeated calls are normal, not_found is a final terminal state, and re-firing the render double-charges. This is exactly the kind of behavioral context an agent needs to avoid costly mistakes.

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

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

Three dense sentences, each earning its place. The description front-loads the core purpose and return values, then provides crucial polling and terminal-state guidance without any 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 single-parameter read-only polling tool with no output schema, the description fully covers what the agent needs: return values, expected duration, polling behavior, terminal states, and the consequence of re-firing. Nothing essential is missing.

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

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

The input schema already fully documents the sole required parameter 'id' with an example format. The description adds no additional parameter-specific semantics beyond restating 'by id,' so the baseline score 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: 'Poll a render job by id.' It clearly defines the tool's output (status, progress, media URL) and, by focusing on polling a single job by id, distinguishes itself from the sibling list_jobs that lists jobs generally.

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 operational guidance: keep polling every 1–3 minutes until done/error without asking the user, and treat not_found as final. It does not explicitly name alternatives or state when not to use this tool, but the polling context is clear and actionable.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds meaningful behavioral context beyond annotations: 'Personal data — show, never republish' and responses with every answer named by field. 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?

The description is one tight sentence that front-loads the operation and includes only value-adding details: source of id, response format, data-handling rule, and read-only/free status. No filler or repetition of schema 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 simple single-resource read with strong annotations, the description covers ID source, response naming, and personal-data handling. It could add explicit not-found or error behavior, but nothing critical is missing 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?

The schema describes pageId and adAccountId with specific guidance, while the description supplies the missing semantics for leadId by pointing to list_linkedin_leads as the source. At 67% schema coverage, this is adequate compensation for the undocumented required 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 clearly states 'One LinkedIn lead by id,' identifying a specific read-by-id operation and even names the source listing tool, list_linkedin_leads. This distinguishes it from list_linkedin_leads, list_linkedin_lead_events, and other sibling 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 tells the agent that the lead id comes from list_linkedin_leads, providing a clear acquisition path. It does not explicitly name alternatives or exclusions, but the singular-by-id framing and source reference give clear usage 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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value beyond annotations by disclosing exactly what the returned metadata includes, including the two links. This gives the agent a concrete expectation of behavior without contradicting the annotations.

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

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

Two concise sentences with no filler. The core purpose and output fields are front-loaded, and the fileId source is stated at the end. 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 single-parameter read-only tool with no output schema, the description provides everything needed: what the tool returns, where the required parameter comes from, and the safety profile. Nothing essential is missing for correct invocation and interpretation.

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

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

Schema description coverage is 100%, with fileId already described as 'the OneDrive item id (from list_onedrive_files)'. The description repeats this provenance rather than adding new semantic detail, so it meets the baseline but does not exceed what the schema already provides.

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

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

The description states a specific verb and resource: 'Fetch one OneDrive item’s metadata', and lists the exact return fields (name, type, size, modified time, webViewLink, webContentLink). This clearly distinguishes it from list_onedrive_files (which lists many items) and get_drive_file (which is not OneDrive-specific).

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 clear usage context by telling the agent to pass fileId from list_onedrive_files, which establishes the prerequisite and source of the identifier. It does not explicitly state when not to use this tool or name alternatives like get_drive_file, but the read-only framing and 'from list_onedrive_files' hint are sufficient for most selection scenarios.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false; the description reinforces this with 'Read-only' and adds non-obvious behavior details: dry-run mode, render budget, next-run timing, queued count, and blocked channels with reasons. 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?

Two front-loaded sentences cover the full status surface without filler. 'Read-only, free' earns its place because it affects tool selection.

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

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

With no output schema, the description must stand in for return values, and it does so by listing on/off, dry-run, fill-ahead days, budget, next run, queued posts, and blocked channels. This is complete for a zero-parameter 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?

The schema has zero parameters, so there is no parameter burden for the description. It still clarifies that the tool operates on 'this brand,' which is enough context given no input is 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 and resource: 'Show the automatic posting refill for this brand' and enumerates the exact status fields. It is clearly differentiated from siblings like set_post_refill and run_post_refill by focusing on status inspection.

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 'Show' framing and explicit 'Read-only, free' signal that this is an inspection tool, giving clear context for when to call it. It does not explicitly name set_post_refill or run_post_refill as alternatives, but the context makes the distinction clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'Read-only'. It adds context that the settings match the web app's Settings pane and that the operation is free, but it does not go beyond annotations in describing side effects or behaviors.

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, each earning its place: the first states the resource and contents, the second anchors it to the web app, and the third confirms safety and cost. No filler or redundancy.

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

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

For a parameterless read-only settings tool, the description is complete enough. It enumerates the settings an agent would receive and gives the scope ('this account'), so an agent can invoke it correctly without 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?

The tool has zero parameters, so parameter semantics are largely irrelevant. Baseline 4 applies because the description still clarifies what data the tool exposes, which is more than the empty schema does.

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 ('Read') and a specific resource ('this account's app settings'), then enumerates exactly what the settings contain: language, theme, and the competitor-watch email toggle. This clearly distinguishes it from write-oriented siblings like update_settings.

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 clear context: it is the read-only counterpart to the web app's Settings pane, so an agent knows when to call it for inspection. It does not explicitly name update_settings as the alternative for changes, but 'Read-only' and the enumerated settings make the usage boundary clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'Read-only, free.' It adds useful behavioral context by explaining what the tool returns (full SKILL.md instructions) and how those instructions should be used afterward. Failure modes are not covered, which is acceptable for a read-only loader.

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 deliver the core purpose, the source of valid inputs, the next step, and the read-only/free nature. There is no filler and the most important information 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?

For a one-parameter, read-only tool without an output schema, the description sufficiently explains what the tool returns and how to use it in a broader workflow. Nothing critical for 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 100% for the single required parameter, including a type, requirement, and example value. The description adds no new parameter semantics beyond restating that loading is by name, 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 uses a specific verb ('Load') and a clear resource ('bundled skill's full SKILL.md workflow instructions by name'), and it references list_skills as the source of valid names. This differentiates it from siblings like list_skills, save_skill, and delete_skill without needing to open 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 states the intended workflow: get the name from list_skills, load the SKILL.md, then follow those instructions with other tools. It does not explicitly spell out when not to use the tool, but the sequencing and source constraint are clear enough for an agent.

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