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

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

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

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

The description is dense but front-loaded, starting with the core action and output before moving into mode-specific details. Every sentence carries useful operational information, with no filler or repetition.

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

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

For a six-parameter tool with no output schema, the description covers the essential behavior: outputs, styling defaults, cue mode, source types, refund behavior, and background/Library handling. It does not fully explain the asynchronous job result shape or how to retrieve the finished output, which keeps it short of complete.

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

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

Schema description coverage is 100%, so parameter syntax is already well documented. The description still adds meaningful semantics by explaining default textStyle behavior, when to set textStyle, the distinction between sentence timing and auto:'words', how cues override transcription, and that burn:false returns only the .srt.

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

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

The description states a specific verb and resource: burn subtitles into a video and also get the .srt. It distinguishes the operation from sibling video tools by emphasizing that nothing is cut or re-rendered and by describing subtitles as the output rather than a general edit.

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

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

It gives clear conditional guidance for the main modes: set textStyle only when the user describes a look, use auto:'words' for phrase-level timing, pass cues for exact untranscribed lines, and use burn:false for only the .srt. It does not explicitly compare this tool with sibling alternatives such as edit_video or dub_video, but the internal usage guidance is strong.

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

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

Annotations already declare openWorldHint=true, idempotentHint=false and destructiveHint=false, and the description's '~A transcription call.' hints that this is a compute/credit-bearing operation rather than a pure metadata read — relevant given readOnlyHint=false. But it does not explain the cost, latency, or async/non-idempotent behavior that the annotations imply.

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

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

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

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

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

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

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

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

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

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

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

The description names a specific verb (analyze) and the exact artifact produced: verbatim transcript, beat list, duration and sampled frame times for a video ad. That is well beyond restating the title. Sibling differentiation is only implicit, via the phrase 'before remixing it', rather than naming a concrete alternative.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Front-loads the core action, then the modes, then the non-destructiveness and cost. Dense with zero wasted words.

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

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

For a 4-param write tool with a fully covered schema and clear annotations, the description conveys scope, non-destructiveness, source of pageId, and cost. It doesn't describe the response, but with no output schema that's an acceptable gap.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real value by indicating pageId's source ('from list_notion_pages') and framing the three optional modes; the swipefile detail largely restates the schema, so it doesn't rise to a 5.

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

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

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

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

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

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

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

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

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

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

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

The description is compact and front-loads the core action before adding access and id-source guidance. The sentence is dense but every clause supports correct invocation.

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

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

For a simple append mutation, the description covers reachability, spreadsheetId sourcing, and row shape while annotations cover safety and schema covers parameters. It does not explain return behavior, but no output schema exists and this is a minor omission.

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

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

Schema coverage is 100%, so all three parameters are already documented. The description reinforces rows as an array of row arrays and clarifies that spreadsheetId can come from create_sheet or list_drive_files, but it omits the optional range parameter.

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

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

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

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

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

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

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

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

Beyond the annotations (which only flag non-readonly, non-idempotent, open-world), it discloses that a new design is created each time, that media is uploaded to Canva first, the required account tier, and that the response is the new design's edit link. That is exactly the kind of side-effect and auth context annotations can't carry.

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

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

Front-loaded with the action and the 'NEW design' constraint, then preconditions and return value; every sentence carries information. The telegraphic fragments ('Free.') are efficient but slightly clipped.

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

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

With no output schema, the description still names the return value (edit link), and it covers the plan gate, media handling, and the create-not-mutate behavior. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds real semantics for the `data` object: values are either text or an image/video expressed as a Library id or link. That goes meaningfully beyond the schema's bare '{ field: value }' and is the main source of call errors otherwise.

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 first sentence states a specific verb (fill), resource (Canva brand template fields) and a scoping constraint that matters: results go into a NEW Canva design rather than editing the template. That distinguishes it cleanly from siblings like list_canva_brand_templates and save_to_canva.

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

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

It gives a clear entry point ('brandTemplateId from list_canva_brand_templates') and states the plan precondition (Pro/Teams/Enterprise), which tells the agent when the call is viable. It stops short of naming when to prefer save_to_canva or export_canva_design instead, so no explicit 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 readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the mutation/idempotency profile is known. The description adds genuinely useful context beyond that: dry-run default with cost quoting, the resumable cursor, the 'backfilled' weaker-evidence labeling, and the unattributed-post rule. It is strong on behavioral nuance, though the 'Free' claim and evidence semantics are the main additions over structured fields.

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

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

Front-loads the core action and destination before channel support and mechanics, and the ordering is logical. It is dense and lengthy, but the length is largely justified by the breadth of channel-specific exclusions, so little is genuinely wasted.

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

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

For a mutation tool with five params and no output schema, the description covers the essentials an agent needs: return-relevant info (count and cost), dry-run/confirm semantics, resumability, and the evidence-strength and attribution caveats that affect downstream use.

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

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

Schema coverage is 100%, so all five parameters are already documented. The description ties confirm and cursor into a coherent two-step resumable workflow (quote cost, then confirm, then continue via cursor), adding flow-level meaning beyond the per-field descriptions, though it largely reinforces what the schema already states.

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

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

States a specific verb (import) and resource (this brand's past posts from a channel) plus the destination (the performance record) and the reason (so hook analysis can draw on history). This clearly distinguishes it from siblings like list_published_posts, collect_post_metrics, or search_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?

Enumerates which channels are supported and, crucially, explains for each unsupported channel (LinkedIn, Reddit, X, Google Business, Telegram) why import is impossible. It also specifies the dry-run-by-default flow and how to proceed (confirm:true, then cursor), leaving nothing to inference.

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

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

Annotations already cover read-only/idempotent/destructive, but the description goes well beyond them: it declares the call is free, explains the shared-workspace scope edge case (billingScope:'member' hides owner card/auto-reload), and even instructs how to phrase the absence of card data honestly. This is exactly the behavioral context annotations cannot carry.

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

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

Front-loaded with the core purpose before the caveats, and every sentence carries non-redundant information. It is on the long side with several ALL-CAPS passages that read as shouting, which slightly hurts scannability but not comprehension.

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

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

With no output schema, the description must explain what comes back, and it does so thoroughly, including the tricky member-vs-owner case that would otherwise cause an agent to hallucinate missing payment data. Nothing an agent needs to call or interpret this tool is missing.

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

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

There are zero input parameters, so the baseline is 4. The description instead documents the meaningful output fields (plan.priceUsd, plan.period, billingScope, plan.memberRate, plan.legacy), which adds real interpretive value even though no input semantics are needed.

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 resource and enumerates exactly what is returned: plan (with priceUsd/period), credit balance, auto-reload state, card-on-file, and caller admin rights. An agent can distinguish this from upgrade_plan, set_auto_reload, and buy_credits purely from the text.

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

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

It states explicit when-to-use ('Call it before upgrade_plan / set_auto_reload to know what's possible') and an explicit precondition/limitation ('members have read-only billing'). The alternative tools are named, so routing is unambiguous.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Every sentence earns its place: purpose, source of parameter values, host-specific rationale, validation behavior, and refusal conditions. The most important action and scope are front-loaded, and the length is justified by the complexity and risk of a generic tool dispatcher.

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

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

Given the tool's complexity as a dynamic dispatcher and the absence of an output schema, the description fully covers how to invoke it, how to source parameters, what validation behavior to expect, and when/why it may refuse. The statement that results match a direct call also informs the agent about return behavior without needing an output schema.

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

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

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

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

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

The description opens with a specific verb and resource: 'Run ANY Hermoso tool by name', and immediately clarifies its unique scope—it can invoke tools not in the session's starting list, including paid-campaign, analytics, and channel-admin tools. This clearly distinguishes it from the many specific sibling tools and from enable_tools.

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

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

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

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, so safety and idempotency are covered. The description adds genuinely new behavioral context: the operation is state-dependent and silently inapplicable once a post has published. It stops short of describing auth/brand requirements, but the added constraint is meaningful.

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

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

Three tight clauses, front-loaded with the core action, then the id source, then the state constraint and alternative. No sentence is filler.

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

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

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

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

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

Schema coverage is 100% and both parameters are fully documented in the schema, including the 'brand' profile-matching rule. The description only reinforces where 'id' comes from, adding nothing beyond the schema, so the baseline 3 applies.

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

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

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

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

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

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

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

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

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

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

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

Two sentences with zero waste. The main operation and preservation behavior are front-loaded, followed by routing guidance and a brief return note.

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

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

With no output schema, the description explains the return value as the served URL. It also covers preservation behavior and cost status. Missing details such as credit amount or processing time are minor for a tool whose annotations and schema are otherwise complete.

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

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

Schema coverage is 100%, and the schema already documents both parameters thoroughly, including default voice behavior and voice-clone naming. The description adds no further syntax or format detail beyond what the schema provides, so baseline 3 applies.

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

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

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

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

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

It gives explicit usage conditions: 'Use when the user likes the video but wants a different narrator voice' and directs language translation to dub_video. No inference is needed to choose between them.

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

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

Discloses behavior the annotations don't: a flat 1-credit cost, that it pulls Meta's live policy pages, the exact return shape (pass/fix/block verdict with verbatim policy quotes and a compliant rewrite), and that it is non-mutating for the creative. This is rich context beyond the readOnlyHint/openWorldHint flags and compensates for the absent output schema.

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

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

Front-loads the core purpose and the cost, then layers in return behavior and use cases. Every sentence earns its place, though the emphasis-heavy single paragraph (caps, em-dashes) is slightly longer than needed.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

States a specific verb and resource ('Empty a range of cells in a Google Sheet') plus a key scope constraint ('leaving the rows themselves in place') that separates it from tab deletion. It explicitly routes the remove-a-whole-tab case to manage_sheet_tabs, so an agent can distinguish it from that sibling without opening either schema.

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

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

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

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

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

Beyond annotations, it discloses meaningful behavior: it reads the page, saves the product to the brand catalog, pins the real product photo to this ad without changing the brand's default, falls back to a real browser and then to link/search data, and says the reply notes that fallback. This adds substantial context that annotations alone (readOnlyHint=false, destructiveHint=false, openWorldHint=true) do not provide.

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

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

The core action is front-loaded in the first sentence, followed by side effects and the render_ad handoff. It is somewhat dense with run-on clauses, but nearly every sentence carries useful behavioral detail rather than filler.

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

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

For an open-world mutation tool with no output schema, the description covers side effects (catalog save, photo pinning), fallback behavior for hidden pages, and the required next step of calling render_ad. It does not describe the shape of the returned creative, but it does enough to let an agent use the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents url, say, style, language, and durationSeconds, including the style enum. The description reinforces the url concept but does not add meaning to the other parameters, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: paste a product page link and get a creator-style video ad planned for that product. It distinguishes itself from siblings by explicitly saying 'Nothing renders here' and routing rendering to render_ad, so an agent can tell it apart from generate_video or render_ad without opening a schema.

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

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

It gives clear usage context (paste a product link, works with or without a saved brand) and a concrete next step: show the concept, then call render_ad with the returned creative, using dryRun:true first for the exact price. It does not name alternatives such as plan_ad or product_sizzle, so the routing is strong on the follow-up but incomplete on sibling selection.

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

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

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

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

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

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

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

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

A no-output-schema mutation-ish tool that nonetheless explains inputs accepted/rejected, cost model and refund behavior, truncation, reframe logic (subject-aware single-offset crop, centre fallback, reframedToSubject/reframeWhy fields), captions default, and return shape (clips[] with URL/title/hook/caption/score/timecode). Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description still adds real value: it explains the default and rationale for captions:false, notes the SUBTITLES default in prose, and mentions captionsBurned/captionNote outcomes tied to the captions parameter. It adds meaning beyond the schema rather than repeating it, warranting a 4.

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

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

States a specific verb ('cut ONE long video into several RANKED, ready-to-post short clips') and resource, and the parenthetical domain list (podcast/webinar/interview/talk/ad -> Reels/Shorts/TikTok) pins the exact use case. A reader can distinguish it from reframe_video, edit_video, and stitch_video without opening schemas.

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

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

Gives explicit accept/reject conditions ('YouTube link... or direct https .mp4', 'NOT supported: TikTok / Instagram / Facebook links, and anything age-restricted, private...'), including the correct fallback ('ask for a direct file or an upload rather than retrying'). It does not name sibling alternatives (e.g. reframe_video for an existing short, edit_video) as when-to-use forks, so it stops just short of 5.

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

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

Annotations declare non-read-only, non-idempotent, open-world behavior, and the description adds genuinely useful context beyond them: billing cost ('Bills as one image generation'), a side effect ('switches this key's active profile like use_brand'), and the guarantee that source branding is removed. It does not describe failure modes or output format, but the added billing and side-effect disclosure is strong.

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

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

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

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

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

With no output schema, the description still conveys what is produced (on-brand static ad, source branding removed), the billing model, the profile side effect, and the sibling alternative. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema: it clarifies imageUrl is the static ad image to clone and that brandId has the side effect of switching the active profile like use_brand — information not present in the parameter descriptions.

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

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

States a specific verb and resource ('STATIC-AD CLONE ... rebuild a competitor/reference STATIC (image) ad as an on-brand version') and explicitly distinguishes itself from clone_video. An agent can identify exactly what this produces (an on-brand static ad) and what it is not.

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

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

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

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

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

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

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

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

It is a dense single block, front-loaded with the core action and brand-scoping, then moves to behavior, cost, and edge cases. Every sentence does work, but the run-on middle section (watching behavior + storyboard rules) could be split for faster scanning.

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

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

There is no output schema, so the description compensates by describing the reply ("says exactly what was watched") and the degraded-caption case. Combined with the cost note and the render_ad handoff, an agent has everything needed to call this and act on the result.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Front-loads the purpose, then layers the accrual model, absent/failed handling, and the metered-X caveat in a logical order with no filler sentences. It is on the longer side with heavy capitalization emphasis, which is slightly dense but each sentence carries distinct information.

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

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

With no output schema, the description still explains what happens to results (stored as a time-series), how missing data is represented, and how skips are surfaced. Nothing an agent needs to invoke this correctly or interpret its effects is missing.

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

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

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

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

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

States a specific verb and resource ('Fetch fresh performance numbers for this brand's recorded posts and store them as a time-series'), and the accrual/skip behavior makes it clearly distinct from a plain metrics reader like post_performance. An agent can tell what it does and how it differs without opening the schema.

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

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

Gives clear context for use: readings are due at ~24h and ~7d, only due readings are collected, and X is skipped unless includeMetered:true is passed (with an instruction to tell the user about credits first). It stops short of explicitly naming a sibling alternative for the 'just show me the numbers' case, so it is strong context without full when-not routing.

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

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

Annotations already signal a non-read-only, open-world, non-idempotent, non-destructive call, and the description adds materially: it spends credits, is free when ads are passed, and auto-pulls Meta ads otherwise. It does not describe failure modes or auth requirements, keeping it short of a 5.

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

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

Front-loads the outcome, then the CONTRACT, then the credit note. The all-caps emphasis is slightly noisy and the sentence is dense, but nearly every clause adds actionable information.

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

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

For a complex, non-read-only tool with no output schema, the description covers the deliverables, the input contract, and the cost. It is largely self-sufficient, missing only explicit mention of what a failed/empty auto-pull returns.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: `ads` is defined as raw ad objects from a prior pull and tied to the tear-down contract, and `competitor` {name, domain?} is explained with domain sharpening the auto-pull match.

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 (tear down) and resource (competitor ad strategy), and enumerates the concrete outputs: hook mix, campaign themes, white space, counter-plays, and owned territories. This is clearly distinguishable from every sibling, including the ad-pull tools it depends on.

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

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

Gives an explicit contract: pass `ads` from a prior pull_competitor_ads/search_meta_ads call, or omit to auto-pull. Names the two upstream siblings by name and explains the consequence of each path (credit spend vs. proven winners).

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

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

Annotations already declare readOnly=false, destructive=true, openWorld=true, idempotent=true, but the description adds substantial behavior beyond them: live key validation with the provider before anything is saved, read-back of the reply from the saved connection, the guarantee that Hermoso never echoes a submitted key, the credential-exposure tradeoff of pasting into chat vs. the app, and the special Apple Ads keypair/setupToken flow. These are real operational facts an agent needs and they are not derivable from the annotations.

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

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

Purpose and provider list are front-loaded and almost every sentence carries operational weight, so there is little padding. The weakness is formatting: a single ~250-word paragraph buries the agent directive ('OFFER BOTH WAYS...') and the field inventory mid-block, which hurts scannability, but the content itself earns its place given 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?

With no output schema, the description still covers outcomes (live check, saved-connection read-back, OAuth fallback link, Apple Ads keypair plus setupToken send-back) and the security expectations. For a 2-parameter but highly variant, open-world mutation tool with nested free-form fields, an agent has everything needed to call it correctly.

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

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

Schema coverage is already 100%, but the schema only offers a free-form 'fields' object; the description supplies the actual per-provider field names and marks required ones with '*' (e.g. mixpanel {username*, secret*, projectId*, region, workspaceId}), which is the only place that contract exists. This adds decisive meaning well 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 first sentence gives a specific verb (connect), a precise resource (an account that links with a KEY rather than a sign-in screen), and the modality (from here, no browser) that separates it from OAuth flows. It also enumerates the exact providers supported, so an agent knows immediately whether this tool applies to the user's request.

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

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

Explicit when-not routing is present: 'An account that connects through the provider's own sign-in screen (OAuth) cannot be connected here: this answers with the link to hand the user instead.' It also gives an explicit agent instruction ('OFFER BOTH WAYS AND LET THE USER CHOOSE') and the alternative path (Workspace > Connectors or the one-click link). Nothing about selection is left to inference.

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

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

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

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

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

Front-loads the core action and the JPG constraint is capitalized and easy to spot. Some enumeration of formats and ad-copy flourishes ('hand someone a PDF of a spreadsheet') run long, but they carry real capability information rather than filler.

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

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

With no output schema, the description correctly fills the gap by describing the return value (a durable Hermoso URL usable in a render or post) and warns against the expiring Microsoft link. Prerequisites, the conditional parameter rule, and format support are all covered.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Front-loaded with the core action and alternatives, and the idempotency and cost notes are valuable. It slips slightly: the long inventory of profile-scoped resources (memory, swipefile, Library, avatars, skills, playbooks, connectors) is expendable, and the credit/refusal logic for draft_brand is fairly verbose for a create tool.

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

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

No output schema, so the description carries the return semantics and does so adequately (returns the existing profile when the name repeats). With safety annotations present, the description fully covers what an agent needs: purpose, alternatives, isolation, idempotency, and cost prerequisites.

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

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

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

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

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

States a precise verb + resource ('Add a NEW profile') and enumerates what counts as a profile (brand, client, creator, personal workspace), which no sibling tool does. It explicitly distinguishes itself from draft_brand and update_brand, so an agent can pick it without opening any schema.

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

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

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

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

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

Annotations already declare the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=true). The description adds the useful cost trait ('Free') and the default location, but it does not warn that the operation is non-idempotent (duplicate folders on repeat calls), which the annotations flag but do not explain.

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

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

It is short and front-loads the core action, but the final sentence ('save_to_canva's folderId then files renders into it') is garbled and forces the agent to parse an awkward clause to extract the workflow hint.

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 creation tool with full schema coverage, no output schema, and annotations covering the safety profile, the description is largely sufficient. Only the missing duplicate/idempotency note and the awkward phrasing keep it from being fully complete.

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

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

Schema description coverage is 100%, so both parameters are already documented. The description restates the parentFolderId default as 'Projects', which slightly diverges from the schema's 'root (default)' wording and adds marginal clarity rather than new 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 verb and resource – 'Create a folder in the user's Canva' – and clarifies the default location (Projects). It implies the distinction from list_canva_folder and save_to_canva by describing creation vs. usage, though it never names the siblings explicitly.

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

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

It gives clear context: create a folder, then use the returned id as save_to_canva's folderId to render files into it. This workflow linkage is helpful, but there is no explicit 'when not to use' or comparison to sibling folder tools.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Annotations already signal non-read-only and non-idempotent behavior, and the description adds the return format (folder id + webViewLink) plus how the ID flows to sibling tools. It also clarifies the find-or-create behavior of save_to_drive, which is useful context beyond the structured annotations. No contradiction with annotations.

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

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

Three sentences, each with distinct value: purpose, return value and downstream usage, and a cross-tool caveat. No filler and the core action is front-loaded. It is appropriately sized for the tool's complexity.

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

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

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

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

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

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

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

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

The description opens with 'Create a folder in the user's Google Drive' — a specific verb and resource — and clarifies it can be nested under parentId. It clearly distinguishes itself from related tools like save_to_drive and update_drive_file by explaining the folder creation role. Unambiguous and immediately actionable.

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

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

The description explicitly tells the agent to use the returned ID as update_drive_file's moveToFolderId or as parentId for a nested folder. It also warns that save_to_drive's folder parameter takes a NAME, not this ID, steering the agent away from a common misuse. This provides direct alternative routing and practical context.

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

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

Annotations already establish that this is not read-only and not destructive. The description adds useful behavioral context by stating the return value includes folder id + webViewLink, which is beyond the annotations. It could mention idempotency implications or duplicate-name behavior, but the essential side effect is clear.

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

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

Three compact sentences, each earning its place: the first explains the action, the second explains how to consume the result, and the third clarifies a critical distinction from save_to_onedrive. No filler or repetition.

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

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

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

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

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

Schema description coverage is 100%, so name and parentId are already documented. The description adds 'optionally nested under parentId' and mentions the root default, but this is largely restating what the schema already provides. It does not add significant new parameter meaning beyond the structured schema.

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

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

The description uses a specific verb and resource: 'Create a folder in the user's OneDrive'. It immediately distinguishes this from Google Drive siblings by naming OneDrive, and it includes the optional parentId nesting behavior. The tool's role is unambiguous.

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

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

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

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

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

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

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

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

The description is front-loaded with the core action, then efficiently covers row formatting, return values, and the connection prerequisite. Every sentence adds practical value with no filler.

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

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

For a simple two-parameter creation tool with annotations and no output schema, the description is complete: it explains the output, optional row filling, and the required Google Drive connection. An agent has enough information to invoke the tool correctly.

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

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

Schema description coverage is 100%, so both parameters are already documented. The description repeats the rows format and header convention without adding meaningful semantics beyond the schema, so the baseline 3 is appropriate.

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

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

The description states a specific verb and resource: create a new Google Spreadsheet in the user’s Drive. It is clear what the tool does, but it does not explicitly differentiate itself from related siblings such as create_doc, save_to_drive, or append_to_sheet.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

States a specific verb (permanently delete), a specific resource (profile), and enumerates the blast radius (brand details, memory, swipefile, Library, assets, avatars, skills, playbooks, chats, connected accounts). It is unambiguously distinguishable from create_brand, update_brand, and get_brand in the sibling list.

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

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

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

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

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

Goes well beyond the annotations (destructiveHint, idempotentHint) by disclosing cross-device delete propagation, that only the roster entry is dropped, that already-rendered ads are untouched, and that the action is reversible via save_creator. This is exactly the behavioral context an agent needs for a destructive operation.

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

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

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

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

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

With annotations covering the safety profile and no output schema, the description supplies the remaining essentials: scope, reversibility, cross-device effect, and what is not affected. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented. The description reinforces the id source (list_creators) but says nothing about the optional 'brand' parameter, adding little beyond the schema. Baseline 3 applies.

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

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

States a specific verb (Remove) and resource (a saved creator) with scope ('from this workspace's cast') and the id source ('from list_creators'). This cleanly separates it from siblings like list_creators, find_creators, save_creator, and update_saved_creator.

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

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

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

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

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

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

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

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

Three short, purposeful sentences cover the operation, default behavior, parameter requirements, and the safety warning. The irreversible caveat is front-loaded before invocation details, with no wasted words.

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

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

For a three-parameter delete tool with no output schema, the description supplies the essential operational details: recoverability, irreversibility, required confirmation, and how to obtain fileId. Given the existing destructive annotation, nothing critical is missing for correct selection and invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value by specifying that fileId comes from list_drive_files and by reinforcing that confirm:true is required. It also ties permanent:true to irreversibility, matching and slightly enriching the schema's parameter descriptions.

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

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

States a specific verb and resource ('Delete a Drive file'), then adds the Trash-vs-permanent distinction so the operation is unambiguous. The resource is clearly Google Drive, distinguishable from siblings like delete_onedrive_file and update_drive_file.

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

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

Gives clear invocation guidance: fileId should come from list_drive_files, confirm:true must be passed, and the user should be consulted before a permanent deletion. It does not explicitly name alternatives or exclusions, but the sibling resource differences are evident from the tool names.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, so the description doesn't need to restate danger. It adds the non-obvious detail that the underlying stored file is deleted too, not just the entry, and that unconfirmed calls are safe previews — behavior annotations don't convey. Lacks mention of irreversibility/restore options, keeping it short of a 5.

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

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

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

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

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

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

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

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

Schema coverage is 100%, so baseline is 3. The description exceeds it by explaining the tri-state meaning of confirm: absent = preview of what would be deleted, true = actual deletion, which the schema's 'true deletes' barely implies. It also notes ids/urls are alternatives rather than both required (consistent with 0 required params).

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

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

States a specific verb (PERMANENTLY delete) and a specific resource scope (images/videos from this brand's Library), and clarifies that both the library entry and the stored file are removed. This distinguishes it cleanly from siblings like delete_drive_file, delete_onedrive_file, and delete_brand.

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

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

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

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false, and openWorldHint=true. The description usefully adds that leads remain unaffected and readable, only delivery stops, and notes the action is read back from LinkedIn and free, which clarifies blast radius beyond the annotations.

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

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

The description is front-loaded with the core action and then adds only the effect scope and cost context. Every sentence carries useful information for deciding whether to invoke the tool.

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

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

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

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

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

Schema description coverage is 100%, so the schema already fully documents subscriptionId, pageId, and adAccountId. The description repeats that subscriptionId comes from list_linkedin_lead_subscriptions but does not add new meaning for the optional pageId or adAccountId parameters.

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

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

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

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

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

Usage is clear: use this to stop real-time lead delivery for a subscription, with subscriptionId sourced from list_linkedin_lead_subscriptions. It does not explicitly state when not to use it or name subscribe_linkedin_leads as the inverse operation, though the context is strong.

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

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

Annotations already indicate destructiveHint=true, so the description adds meaningful context by disclosing that the item moves to the OneDrive recycle bin and is recoverable there. It also communicates the confirmation safeguard, which is valuable behavioral context beyond the schema and annotations.

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

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

The description is three short sentences with no filler. It front-loads the core behavior, then covers the parameter source and confirmation requirement. Every sentence earns its place.

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

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

For a simple two-parameter delete operation with no output schema, the description covers the action, the recoverability consequence, the source of the identifier, the required confirmation flag, and the user-confirmation step. Nothing essential is missing for an agent to invoke it correctly.

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

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

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

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

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

The description states a specific verb ('Delete') and a specific resource ('a OneDrive item'), and immediately clarifies scope by noting it is a recycle-bin move rather than a permanent purge. This clearly differentiates it from related siblings like update_onedrive_file, get_onedrive_file, and save_to_onedrive.

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

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

It gives concrete usage instructions: pass fileId from list_onedrive_files, pass confirm:true, and confirm the exact file with the user first. This is strong practical guidance, though it does not explicitly name alternatives or conditions when this tool should not be used.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, but the description adds non-obvious behavior the annotations cannot convey: the delete is recorded cross-device so the playbook will not reappear on the next sync, and the item is characterized as minor and re-creatable. It stops short of 5 because it says nothing about auth requirements or failure modes.

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

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

Three short sentences, front-loaded with the action and identifier, then the durability semantics, then the confirmation guidance. No filler and every sentence carries information.

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

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

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

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

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

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

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

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

States a specific verb and resource ('Delete a saved playbook') plus the identifier source, and the id-provenance callout ('from list_playbooks') clearly distinguishes it from the sibling save_playbook and the list_playbooks read tool.

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

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

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

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description benefits from that lower bar. It still adds non-annotation context: only custom skills are removable, and the deletion is described as minor/re-creatable so no confirmation is needed — useful impact guidance for a destructive call.

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

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

Three short sentences, front-loaded with the primary action and scope, then the constraint, then the confirmation policy. No filler or repetition.

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

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

For a two-parameter delete with no output schema and full schema coverage, the description covers scope, the id source, non-deletable resources, and confirmation policy. It omits only failure behavior for an invalid or non-custom id, a minor gap given the annotations.

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

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

Schema description coverage is 100% and both parameters are documented in the schema, so the baseline is 3. The description reinforces that 'id' is a custom-skill id sourced from list_skills but adds nothing about the 'brand' parameter's semantics beyond what the schema states.

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

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

Specific verb ('Delete') + resource ('skill') + scope ('CUSTOM skills', excluding built-ins and recipes), and it names the sibling that supplies the id (list_skills). An agent can immediately distinguish it from save_skill, get_skill, list_skills, and delete_playbook.

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

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

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

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description adds substantial behavioral context beyond them: the 24h 'too early' rule, the unmeasured-vs-zero distinction with dated platform examples, the <5-post baseline fallback and its non-transferability, the inability to see conversions, and the 0-credit cost. This is unusually rich disclosure.

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

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

Long and heavy with all-caps emphasis, but front-loaded with the core purpose and problem-routing before the four refusals. Nearly every sentence carries actionable information; it is dense rather than padded, though the volume pushes against ideal brevity.

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

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

No output schema exists, and the description compensates by stating that 'nothing here needs fixing' is a valid result, that summary must be printed verbatim, and that fallback baselines are attributed in the output. Complete for a diagnostic read tool.

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

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

Schema description coverage is 100%, so the schema already documents limit, channel, and converting with detailed semantics (baseline built from every post, channel enum list, when to pass false). The description largely reinforces rather than extends this, 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?

Opens with a specific verb+resource ('WHAT TO FIX NEXT, post by post') and immediately distinguishes itself from the sibling post_performance: 'post_performance tells you which hook is AHEAD; this tells you what is WRONG with a given post.' An agent can route between the two without opening either schema.

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

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

Explicitly maps diagnostic outcomes to next actions (under-distributed → mine_angles, list_hooks, plan_variations; seen-not-held → plan_variations; seen-held-not-converting → offer problem), names the sibling it is not, and specifies the exact condition for the converting:false parameter. Nothing is left to inference.

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

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

Goes well beyond the annotations (destructive/idempotent/openWorld): explains that stored credentials are dropped, that all provider tools stop working, that already-published posts/campaigns are unaffected, and critically that the provider-side grant is NOT revoked. It even discloses the unconfirmed-call behavior and what to relay to the user.

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

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

Front-loaded with the purpose, with CAPS emphasis reserved for the truly critical caveats (no provider-side revoke, browser needed to reconnect). It is dense and somewhat repetitive with the schema wording, and the long parenthetical provider list adds bulk, but every sentence carries decision-relevant content.

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

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

For a destructive, irreversible-from-the-agent's-perspective tool with no output schema, the description covers the essentials: what is destroyed, what is not, provider-side side effects, cross-brand impact, and how to route the user. An agent has everything needed to call it correctly and communicate the result.

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

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

Schema coverage is 100% and the schema descriptions already carry the account/confirm/provider semantics, so the description largely restates them. It adds only light invocation context ('name the provider, then confirm:true'), which is not enough to exceed the high-coverage baseline.

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

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

States a specific verb+resource ('disconnect a third-party account from this workspace') and enumerates the concrete provider scope. It is clearly distinguishable from adjacent siblings like connect_connector, leave_connector, and list_connector_accounts.

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

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

Explicit when-and-how guidance: 'Name the provider to the user, then call with confirm:true', use list_connectors for exact provider ids, and use the account param to remove only one account on multi-account channels. It also flags that reconnecting needs a browser, i.e. this is not agent-reversible.

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

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

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

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

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

Front-loaded with purpose, cost, and the verification warning in that order, with no filler sentences. The bala.com example costs a clause but is concrete and earns its space; slightly denser than it needs to be with parenthetical asides.

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

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

No output schema exists, and the description compensates by sketching the returned object ({name, products, logo, …}) and naming the two fields to verify. Field-level detail of the full returned profile is missing, but the essential decision-relevant output information is present for a 5-param, all-optional tool.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description gives a precise verb and resource ('Localize a finished video into another language') and even sharpens the scope with 'WITHOUT re-rendering it.' It does not name or explicitly distinguish itself from siblings like localize_ad or edit_video, so a 4 rather than a 5.

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

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

Usage context is only implied: 'Pass the video and the language' explains the call, not when to choose this over localize_ad or another localization/edit tool. There is no when-not guidance or named alternative. The only real routing hint is the param-level note that script should be omitted unless the auto-transcript is wrong.

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

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

Goes well beyond the annotations: it discloses that the copy is INDEPENDENT of the original and that it publishes even on channels where the original already ran, which is exactly the side-effect context an agent needs for a destructiveHint=true, non-idempotent tool. It stops short of covering permissions/brand-pinning requirements or what the call returns.

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

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

The core action and the override capability are front-loaded, and the sibling alternative is placed at the end where it belongs. It is dense but every sentence carries information; the all-caps emphasis (NEW, INDEPENDENT, ANY, REFUSED) is slightly noisy for 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?

For a 21-parameter mutation with no output schema, the description covers what is copied, how scheduling is chosen, and independence from the source — enough to call it correctly. The one remaining gap is that with no output schema the agent is not told what comes back (e.g. the new post's id) for follow-up calls.

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

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

Schema coverage is already 100%, so baseline is 3, but the description adds semantic value the schema does not: it enumerates exactly which fields carry over (caption, media, per-channel captions, title, description, tags, board/Page/company Page/listing) and states that any of them can be overridden in one call. It also explains the at-vs-useQueue choice in prose.

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?

Starts with a specific verb+resource ("Copy an existing scheduled or already-published post into a NEW queued post") and immediately contrasts it with the near-sibling retry_scheduled, so the agent can tell the two apart without opening either schema.

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

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

Gives explicit when-to-use cases (rerun a creative, reuse a winning post as a starting point, re-send after publication) and an explicit exclusion: "To re-fire only the channels that FAILED, use retry_scheduled instead." That is a named alternative with the condition that selects 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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false), which only signal an open-world mutating call. It discloses what is preserved ('composition, aspect ratio, people and every untouched line of text stay as they are'), the brand-name/logo pinning behavior, the product-label lookup side effect, and the cost model ('One image edit's credits', 'one small extra charge finds the product first').

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

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

Front-loads the core action and examples before flag semantics and sibling routing, and nearly every clause carries information (cost, pinning, label check). It is a dense single paragraph, however, which makes the flag rules harder to scan than the content warrants.

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

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

No output schema exists, yet the description states the return ('returns the new image URL') and the cost, covers the required inputs with accepted formats, explains each optional flag's effect, and routes to the right siblings. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so every parameter including dryRun and mask is already documented in the schema; the description's removal/fixLabel prose closely mirrors the existing schema descriptions. It adds modest nuance (tied flag interactions, mask cross-reference to generate_image) but the structured data already does the heavy lifting, so baseline 3 applies.

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

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

States a specific verb+resource ('EDIT an existing image in place with a plain-language instruction') and immediately contrasts the scope with siblings ('For a new image from a prompt use generate_image; to rebuild a competitor's ad for your brand use clone_static'). An agent can distinguish it from generate_image, clone_static, and remix_static without opening any schema.

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

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

Gives explicit routing rules to alternatives at the end, plus conditional triggers for each flag: removal:true 'when the edit STRIPS text, branding or an object', fixLabel:false 'turns that off', and mask 'For a precise region'. When-to-use and when-not-to-use are both covered.

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

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

Annotations declare the safety profile (not read-only, not destructive, open-world, non-idempotent), and the description adds substantial context beyond them: what is preserved (motion, timing, framing, cut, lighting unless the change needs light), how the instruction is wrapped, that literal:true bypasses the wrapper, that previewFirstFrame quotes the clip and runs nothing else, and that the reply scores fidelity and flags overreach. 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 core capability and exclusions are front-loaded, and nearly every sentence carries operative information. It is dense and somewhat run-on in the middle (the lock-wrapping and preview sentences), which costs readability but not correctness.

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

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

For a 13-parameter, non-idempotent, open-world mutation with no output schema, the description covers the essential decision points: what changes vs. what is preserved, preview-first cost control, alternatives, duration limits, and what the response reports. Remaining parameter details are fully documented in the schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description earns above baseline by explaining the intent behind several parameters that the schema only states mechanically: elements as product/identity grounding, lighting forcing behavior, literal:true, and the previewFirstFrame → previewAt → previewStill workflow. It does not touch engine, faceRoute, keepAudio, reference or interactionId, so not a 5.

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

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

The description states a specific verb and resource ('swap an object in a video' / 'edit an existing clip') with concrete examples, and explicitly names the sibling tools it is not for (post_edit, generate_video, render_ad, dub_video, recast_motion). An agent can distinguish this from every nearby editing tool without opening a schema.

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

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

It gives explicit when-to-use guidance with example instructions, names alternatives and the conditions that select them, and adds workflow rules ('one change per call holds best', use previewFirstFrame before paying for the clip, best on 3-15s clips). Nothing about tool selection is left to inference.

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

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

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

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

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

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

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

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

No output schema and one parameter, yet the description fully covers usage, alternatives, client behavior, rationale, and valid group values. An agent has everything needed to decide and invoke correctly.

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

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

Schema coverage is 100% for the single param, so the baseline is 3. The description adds the full list of valid group names (core, research, create, channels, channel_admin, analytics, ads, files, workspace, 'all') that the schema lacks (no enums), plus worked example calls, which meaningfully extends beyond the schema.

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

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

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

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

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

Gives explicit when-to-use ('CALL THIS WHEN A WHOLE AREA IS IN PLAY') with concrete triggers for ads and analytics, names the alternative routes (call_tool, find_tools, ?tools=all), and states the client-compatibility condition that governs whether it will actually take effect.

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

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

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

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

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

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

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

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

With no output schema, the description helpfully enumerates the return fields (status, connector, job id, workspace, shape-only input echo), which is what the agent needs to know. Only minor gaps remain, such as ordering or limits on 'most recent occurrences'.

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

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

Schema coverage is 100% and the single fingerprint parameter is already documented as 'the `fp` value from list_errors'. The description restates this mapping but adds no format or syntax detail beyond the schema, so baseline 3 applies.

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

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

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

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

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

The parenthetical '(from list_errors)' tells the agent where the required fingerprint comes from, which is the key prerequisite. It lacks an explicit 'use this when... not that' exclusion, but the usage context is clear.

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

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

Annotations declare this is a non-read-only, open-world, non-idempotent but non-destructive call; the description adds what that actually means: files are written into the Library, pdf/pptx behave differently by returning a 24-hour download link, proQuality can fail on unlicensed premium elements, and the call is free. Failure mode, side effect, cost and output destination are all 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?

Front-loaded with the verb, resource and destination, then dense parenthetical clauses; nothing is filler and 'Free' is a useful one-word cost signal. It is written as a single run-on block with semicolon-chained parameters, which costs some scannability for an 8-parameter tool.

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

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

For an 8-param, no-output-schema export tool, an agent has enough to call it correctly: how to identify the design, what each format returns, page selection, quality modes and the premium-element failure case. Remaining gaps (dimension bounds, transparency) are fully documented in the schema, and return shape is largely implied by the Library-vs-link distinction.

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 genuinely new semantics beyond the schema — notably that quality defaults follow the design's shape, and that format choice determines whether you get a Library file or a link. It omits width, height and transparentBackground, which are left entirely to the schema.

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

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

States a specific verb (export), a specific resource (one of the user's Canva designs, by id or link), and the destination (Hermoso Library) with the downstream intent (post, schedule, ad creative). This cleanly separates it from save_to_canva, list_canva_designs and autofill_canva_template without the agent opening a schema.

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

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

The purpose clause implies when to reach for it (you need actual files ready to publish or use as creative), and the format parenthetical gives explicit conditional routing — png/jpg/mp4/gif land in the Library, pdf/pptx return a link instead. It stops short of naming alternatives or exclusions (e.g. use list_canva_designs to find the designId), so no explicit when-not guidance.

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

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

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

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

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

Front-loads what the export produces, then covers the create/write modes, history scope, row cap, and cost in densely packed sentences. No filler; every sentence carries an operational fact.

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

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

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

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

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

Schema coverage is 100%, so the baseline is 3, but the description clarifies the create-vs-write distinction for parentPageId/databaseId and the meaning of historyDays. dataSourceId is only indirectly covered via 'matching its columns by name', so it isn't fully fleshed out beyond the schema.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Schema description coverage is 100%, so the schema already documents limit, title, and collection with defaults and formats. The description does not add meaningfully richer parameter semantics beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: turning a swipefile collection into a Google Slides deck with one slide per saved ad. It clearly explains what is produced and what each slide carries, but does not explicitly differentiate this tool from sibling tools such as create_doc, save_to_drive, or list_swipefile.

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

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

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

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, openWorldHint=true, and the description adds real context on top: it is free and keyless, requires a confident match, returns 0 screens and saves nothing on failure, and on success writes durable URLs to the brand. Minor gap: it doesn't say where in the brand the screens land or how many are typically pulled, but the risk/outcome picture is well covered.

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

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

Front-loads what the tool does, then purpose, then inputs, then failure behavior - a sensible order. It is denser than it needs to be (parenthetical template syntax and repeated emphasis in caps), but nearly every clause carries actionable information.

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

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

With no output schema, the description still explains the return contract (screens saved to the brand as durable, immediately usable URLs) and the failure contract (0 screens, nothing saved). For a 3-param, all-optional tool with full schema coverage and rich annotations, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds a precedence rule the schema does not encode - storeUrl is 'read exactly' and takes priority, with appName as the fallback that defaults to the saved brand's name. That precedence and the strictness of storeUrl matching are genuinely useful selection guidance.

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 ('Pull an APP brand's REAL store screenshots ... into the workspace brand') and scopes it to Google Play / App Store. It also names the downstream consumer (make_template_ad with template 'app-ui-tour'), so an agent can place it among the many generate/render siblings 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?

Gives explicit triggering conditions: brand has 0-1 app screens on file, or the user asks to pull screenshots, plus the specific follow-on call. It also states the negative path - ambiguous/unknown matches return 0 screens and should be relayed, not retried with guesses - which is a when-not-to-use rule most descriptions omit.

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

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

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

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

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

The description is a single, well-structured sentence that front-loads the action, the accepted input, and the resulting output. Every phrase contributes necessary information with no waste.

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

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

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

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description repeats the URL input example and does not mention the optional 'name' parameter or add syntax beyond what the schema provides, making 3 the appropriate baseline.

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

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

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

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

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

The description implies usage by describing the accepted input ('a /generated/… path or any URL'), but it never states when to use this tool versus alternatives or any exclusions. Guidance is present only at an implied level.

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

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

Annotations cover the safety profile (non-read-only, open-world, non-idempotent, non-destructive), and the description adds real behavioral context beyond them: it consumes credits, enforces an allowlist that rejects other paths, and returns raw provider JSON that is large and messy. That is materially useful disclosure for a mutation-adjacent, credit-spending call.

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

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

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

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

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

For a generic passthrough with a 2-param schema, an allowlist constraint, and no output schema, the description supplies everything needed: scope, allowlist, param-name variability, cost, and return-format expectations. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the schema already documents path and params, so the baseline is 3. The description goes further by noting that param names vary per endpoint (handle for profiles, query for keyword searches, subreddit for Reddit) and gives example shapes, which is genuine added meaning.

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

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

The description names a precise verb and resource — 'Generic escape hatch for any ALLOWLISTED long-tail social/web endpoint' — and explicitly frames it against the dedicated search_* siblings. An agent knows exactly what class of call this performs without opening the schema.

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