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

Annotations already declare the write profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the bar is lower. The description still adds real behavioral context the annotations lack: source-is-not-re-rendered, background execution landing in the Library, and the notable 'no speech is refused and refunded' failure/refund behavior.

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

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

Front-loaded with the core action and outcome, then branches into style/cue/burn options. Dense and slightly list-like across several long sentences, but every sentence carries information an agent needs; little is wasted.

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

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

No output schema exists, yet the description explains the return surface (.srt output, burn:false mode, Library landing) and accepted input types (file/URL, YouTube/Vimeo page, TikTok/Reel/X link). Sufficient for correct invocation, though the exact job/response shape at completion is only gestured at.

Complex tools with many parameters or behaviors need more documentation. 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 67% schema coverage the schema documents several params, but the description adds semantics beyond it: the textStyle default (white sentence case, thin outline, bottom), the distinction between timed-per-sentence and auto:'words', and that cues burn lines 'exactly, untranscribed' with reel/stage-direction syntax. Only wordsPerCue is left undocumented.

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

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

States a specific verb+resource ('Burn subtitles into ANY video and get the .srt too') and immediately scopes it against likely siblings by clarifying 'nothing is cut or re-rendered', separating it from edit_video/reframe_video/stitch_video. An agent can identify the tool's job 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 concrete when-to-use rules: set textStyle only when the user describes a look, use auto:'words' for word-timed phrases, pass cues for your own lines, burn:false for .srt only. It does not name alternative sibling tools (e.g., edit_video or dub_video), so the routing guidance is clear but not fully disambiguated.

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

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

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

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

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

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

Given the annotations, the 100% schema coverage, and the tool's moderate complexity, the description provides enough for an agent to invoke it correctly. It covers resource eligibility and parameter sourcing. It lacks explicit guidance on what the tool returns after appending, but that is not essential for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by telling the agent exactly where to get spreadsheetId ('pass the spreadsheetId from create_sheet', 'find its id with list_drive_files'), which is actionable guidance beyond the schema's generic parameter description.

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

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

The description states a specific verb ('Append rows') and a specific resource ('a Google Sheet'), and adds meaningful scope: sheets Hermoso created or the user handed over via the file picker. It is clearly distinguishable from sibling tools like append_to_doc and update_sheet.

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

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

The description gives clear context for when to use the tool by explaining which sheets are eligible and how to obtain the spreadsheetId from create_sheet or list_drive_files. It does not explicitly contrast with alternatives like update_sheet or clear_sheet_range, so it stops short of a 5.

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

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

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?

Beyond the read-only annotations, it discloses cost ('free'), admin-rights visibility, and a critical shared-team-workspace behavior: a member sees plan and balance only, card and auto-reload are hidden (billingScope:'member'), and agents must not claim no card exists. This is exactly the kind of behavioral context annotations cannot supply.

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

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

The description is front-loaded with the core purpose and every major sentence adds useful routing or permission information. It is somewhat long and emphatic for a simple status tool, with minor redundancy against annotations ('Read-only'), but the length is mostly justified by the member-scope caveat.

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

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

With no output schema, the description fully enumerates the returned fields and the member-scoped visibility rules. Combined with annotations covering safety and idempotency, it gives an agent everything needed to call and interpret this tool.

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

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

The tool takes zero parameters, so there is no parameter semantics to clarify; the baseline for a 0-param schema is 4. The description does not need to compensate for schema gaps because the input schema is empty.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Show this account's billing at a glance') and enumerates exactly what is returned: plan id/label/actual billed price, credit balance, auto-reload, card on file, and admin rights. It also differentiates the tool from upgrade_plan and set_auto_reload by positioning it as the prerequisite read.

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

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

It explicitly says to call it before upgrade_plan / set_auto_reload to know what's possible, notes it is read-only and free, and explains the member/workspace-owner split for billing visibility. That gives both the trigger and the permissions context for when this tool is appropriate.

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

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

The description goes well beyond the sparse annotations (readOnlyHint=false, openWorldHint=true) by disclosing that the tool charges a saved card, requires billing-admin rights, produces a Stripe checkout URL on first purchase, and mentions the 10-minute validity of quote_token plus idempotency on retried confirm. It also reveals the HTTP 402 MPP challenge flow and the config endpoint, giving a full behavioral picture. No contradiction with annotations.

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

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

The description is long but every sentence earns its place given the tool's three distinct paths, auth requirements, and exception cases. It is front-loaded with the core use case and uses typographic emphasis (caps, bold) to highlight the machine-payment lane. The structure flows logically from normal flow to edge cases to alternative tools, keeping it scannable despite its length.

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

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

With no output schema, the description must explain result formats, and it does: list returns packs with id·credits·price, quote yields quote_token, first purchase yields a Stripe checkout URL, and machine-payment answers with an HTTP 402 MPP challenge. It also covers prerequisites, auth, exclusions, and sibling alternatives, making the tool fully callable without external documentation.

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

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

Though the schema covers 100% of parameters, the description adds critical workflow semantics: 'Call with no argument to list the available packs,' explains that pack selects a pack id and triggers a quote, confirm:true actually charges, and quote_token binds the exact price, has 10-minute validity, and makes retries idempotent. This is precisely the kind of meaning that lets an agent invoke the tool correctly without guessing.

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

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

The description clearly identifies the resource (credit packs) and the action (top up/buy), and explicitly delineates three distinct paths: listing packs, one-click charge with quote_token+confirm, and the machine-payment lane for credential-holding agents. It also distinguishes itself from subscriptions and names the sibling set_auto_reload, leaving no ambiguity about what this tool does.

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

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

The description gives explicit when-to-use guidance: it starts with 'Out of credits? Top up with a credit PACK,' explains the exact call sequence for quoting and confirming, notes when the checkout URL applies vs. the one-click path, and explicitly routes auto-reload to set_auto_reload ('To stop running out entirely...'). It also states that subscriptions are handled by a person, preventing misuse.

Agents often have multiple tools that could apply. Explicit usage 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 flag destructiveHint=true and readOnlyHint=false, so the destructive nature is known. The description adds valuable behavioral context beyond that: the two-call confirm flow, the echo mechanism (confirmCells) that catches naming mistakes, the fact that there is deliberately NO default range, that the clear is read back and reported as confirmed only if the range is truly empty, and that rows are left in place. This is rich, non-obvious behavioral disclosure that goes far beyond the structured data.

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

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

Every sentence earns its place. The description front-loads what the tool does, then explains the safety protocol, the echo rationale, the no-default-range design, and the alternative tool — all in roughly 110 words. Nothing is wasted or redundant with the schema or annotations.

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

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

For a destructive mutation tool with 5 params, no output schema, and only partial schema coverage, this description is remarkably complete. It covers the operation, the safety workflow, the exact parameters to set in each call, a common failure mode, the absence of a default, the post-condition verification, and points to the sibling for a related but different task. There is no meaningful gap an agent would face when invoking it correctly.

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

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

Schema description coverage is only 40%: 'range' and 'confirmCells' have descriptions, but 'confirm' and 'sheetUrl' and 'spreadsheetId' do not. The description partially compensates by explaining confirm (the two-call protocol) and confirmCells (echo the filled-cell count the unconfirmed call reported). It doesn't explain the relationship between sheetUrl and spreadsheetId, but the core usage semantics of the non-obvious parameters are well covered. With 5 params and 40% coverage, the description carries a large share of the burden and does so effectively.

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

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

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

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

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

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

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

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

Annotations 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 declare mutation semantics (destructiveHint=true, idempotentHint=true, openWorldHint=true) but say nothing about validation, credential safety, or special-case flows. The description adds all three: the key is validated live with the provider before anything is saved, the reply is read back from the saved connection, Hermoso never echoes a submitted key, pasting in chat leaves the key in conversation history, and Apple Ads without key material first generates a key pair and returns a public key plus a setupToken. That is substantial behavior beyond the annotation set, with no contradiction.

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

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

It is long, but the length is driven by 13 providers with non-overlapping field sets and by genuine special cases (Apple Ads key generation, OAuth fallback), so nearly every clause earns its place. The purpose is front-loaded before the provider list and the credential-handling policy. The dense single-paragraph layout and mid-sentence ALL-CAPS instruction cost it a point on structure.

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

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

With no output schema, the description still tells the agent what comes back ('the reply is read back from the saved connection') and what the Apple Ads special case returns (public key + setupToken). Combined with the provider/field inventory, live-validation behavior, and the OAuth fallback, nothing an agent needs to call this correctly is missing.

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

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

The schema only says fields are 'that provider's own field names and values' and defers explicitly to the description, so the description is the sole source of per-provider parameter meaning. It enumerates each provider's exact field names with '*' marking required ones (e.g. stripe {apiKey*}, mixpanel {username*, secret*, projectId*, region, workspaceId}), which is far more than the 100%-covered top-level schema provides.

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

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

States a specific verb+resource with scope: 'Connect an account that links with a KEY rather than a sign-in screen, from here, with no browser', then enumerates the exact 13 supported providers. It explicitly carves itself away from the OAuth path ('An account that connects through the provider's own sign-in screen (OAuth) cannot be connected here'), so an agent can distinguish it from sibling connector tools like list_connectors, set_connector_accounts, and leave_connector 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 and when-not-to-use guidance: use this for key-based providers, and if the provider is OAuth-only, 'this answers with the link to hand the user instead'. It even prescribes agent behavior for the credential-handling decision ('OFFER BOTH WAYS AND LET THE USER CHOOSE') and contrasts the two paste locations, which is the real routing decision the agent must make.

Agents often have multiple tools that could apply. Explicit usage 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: conversion runs on Microsoft's servers, nothing is re-encoded locally, output lands on a durable Hermoso URL while Microsoft's link expires in minutes, and OneDrive must be connected with no new permission needed. That is exactly the kind of operational context annotations don't cover.

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

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

Front-loaded with the core action and the hard JPG constraint, then use cases. It is long and includes a lengthy format enumeration plus some flourish ('which is the point'), but nearly every sentence carries selection-relevant information.

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

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

No output schema exists, and the description compensates by explaining where the result is stored (durable Hermoso URL) and warning against the expiring Microsoft link. Combined with the stated auth requirement, an agent has everything needed 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%, so baseline is 3, but the description adds rationale the schema lacks — explaining that Microsoft refuses the JPG call without both width and height — reinforcing why the constraint matters rather than just restating it.

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

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

States a specific verb (convert) and resource (a file in the user's OneDrive) with the target formats (PDF/JPG), and it clearly distinguishes itself from list_onedrive_files/get_onedrive_file by describing transformation rather than retrieval.

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

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

Provides concrete when-to-use scenarios (client deck to ad images, PSD/raw to JPG, spreadsheet to PDF) and states a hard prerequisite (OneDrive connected, JPG needs width+height). It doesn't explicitly route to a sibling alternative, so it falls short of a 5.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, but the description adds real context beyond them: profile isolation ('nothing leaks between them'), the concrete idempotency semantics (same name returns the existing profile), and the cost model. It does not describe what the response body contains, which is the main remaining gap.

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

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

Front-loaded with the action and scope, then alternatives, then the idempotency and cost caveats; every sentence carries information. Heavy capitalization for emphasis is slightly noisy but does not bloat the text.

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

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

For a two-parameter creation tool with no output schema, the description covers purpose, isolation, idempotency, cost, and sibling routing. It stops short of saying what the returned profile object looks like or what identifier the agent should reuse, which is the only notable 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 description coverage is 100% and both parameters (name, activate) are documented in the schema, so the baseline of 3 applies. The description reinforces the switch semantics ('switch to it') but adds no syntax or format 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 ('Add a NEW profile') and enumerates the domain it covers (brand, client, creator, personal workspace), which lets an agent distinguish it from get_brand, list_brands, use_brand, and update_brand without opening a schema. The parenthetical definition of what a profile is adds precision rather than restating the title.

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

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

Explicitly routes the agent to the sibling tools that continue the workflow ('Use draft_brand to FILL it and update_brand to edit it') and gives the cost condition that selects between them (free now; ~50-credit cascade only when draft_brand runs). The duplicate-name behavior also tells the agent it is safe to call speculatively.

Agents often have multiple tools that could apply. Explicit usage 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?

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, covering the write-non-destructive profile. The description adds useful behavioral context: rows are written as an array of row arrays with the first row as headers, and the call returns the spreadsheet id plus URL. It also notes the cross-tool connection requirement. No contradiction with annotations.

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

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

Three sentences, each earning its place: primary action with examples, row format, and return value plus prerequisite. The example list ('swipefile, ad list, or performance report') is slightly illustrative but useful for selecting the tool. Well front-loaded with the core behavior.

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

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

For a 2-parameter creation tool with no output schema, the description covers the essential call information: what is created, how to supply optional rows, what the response contains, and the required connector. Minor absences — default title behavior, handling of title collisions, or explicit guidance to prefer append_to_sheet for existing spreadsheets — keep it from a perfect score.

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

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

Schema description coverage is 100%, with both rows and title documented in the schema. The description reinforces that the first row is headers and that rows are optional, but adds little beyond the schema's own parameter descriptions. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description begins with a crisp verb+resource statement — 'Create a new Google Spreadsheet in the user’s Drive' — and adds the optional fill-with-rows behavior. It clearly distinguishes from siblings like create_doc and append_to_sheet by emphasizing a brand-new spreadsheet, leaving no ambiguity about the tool's core function.

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

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

The description gives concrete usage examples (export a swipefile, ad list, performance report) and states the hard prerequisite of having Google Drive connected, including where to configure it. It doesn't explicitly name the alternative for appending to existing sheets, but the 'new spreadsheet' framing implies when to use this over append_to_sheet.

Agents often have multiple tools that could apply. Explicit usage 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 indicate destructive, idempotent, and open-world behavior, and the description adds crucial scoping: only the webhook is removed, while leads remain intact. 'Read back from LinkedIn' also discloses the external side effect, and there is no contradiction with the annotations.

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

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

Three short sentences front-load the core action and immediately clarify the destructive scope. Every sentence earns its place: the action, the non-destructive effect on leads, and the external synchronization/cost 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?

Even without an output schema, the description covers what the call does, what it affects, and where to get the required parameter. The idempotent and open-world hints come from annotations, making this complete enough for an agent to select and 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?

The schema already documents pageId and adAccountId, and the description adds meaning for the required subscriptionId by tying it directly to list_linkedin_lead_subscriptions. Since 67% of parameters are schema-described, the description meaningfully compensates for the remaining undocumented parameter.

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

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

The description opens with the specific verb 'Remove' and the exact resource, 'a lead notification webhook', and anchors the required subscriptionId to its source, list_linkedin_lead_subscriptions. It also explicitly scopes what is not affected ('Leads themselves are unaffected'), which distinguishes it from any lead-deletion or subscription-creation 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?

The description tells the agent where to obtain the subscriptionId and makes the intended use case clear: stop real-time delivery while keeping leads readable. It does not explicitly enumerate exclusions versus every sibling tool, but the context is sufficient for 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 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 (destructiveHint/idempotentHint/openWorldHint) by disclosing the concrete consequences: stored credentials are always dropped, every provider tool stops working immediately, already-published posts/campaigns are unaffected, and revoke-at-provider behaviour varies by provider (Threads, Microsoft lack revocation endpoints). It also warns that reconnecting requires the user's browser and that the unconfirmed call reports revoke status.

Agents need to know what a tool does to the 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 its main consequence before the provider-specific caveats, and every sentence carries information. It is dense and the all-caps emphasis plus the duplicated browser-warning (also present in the confirm param schema) make it slightly noisier than necessary.

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

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

For a destructive, no-output-schema tool, the description covers everything needed: scope, irreversible credential loss, provider-dependent revocation, the confirm requirement, and how to enumerate valid provider ids. Nothing essential to correct invocation 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 already 100%, so the baseline is 3. The description nonetheless adds usable meaning: why confirm must be true (browser-based reconnection) and that account removes ONLY one handle while keeping others, plus pointing to list_connectors for valid provider ids.

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

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

States a specific verb and resource — 'Disconnect a third-party account from this workspace' — and enumerates the affected providers (Meta, Google Ads, YouTube, Slack, ...). An agent can immediately distinguish this from connect_connector and from rendering/posting tools.

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

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

Gives a concrete workflow: 'Name the provider to the user, then call with confirm:true. Use list_connectors for the exact provider ids,' and explains that the account param narrows removal on multi-account channels. It does not, however, mention when NOT to use it, e.g. versus the sibling leave_connector, so the alternative-selection guidance is incomplete.

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

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

Annotations cover the safety profile (destructiveHint=true, openWorldHint=true, non-idempotent), and the description adds context beyond them: zero credit cost, that it scrapes external sources, that save:true overwrites the saved profile, and that the tool cannot ask the user for confirmation. The destructive/overwrite behavior aligns with destructiveHint rather than contradicting it.

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

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

Front-loaded with purpose and cost, then the risk warning, then the remedy. All sentences carry information, though the bala.com/shopbala.com illustration is verbose for the point being made.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 supplies the return shape, the cost, the verification obligation, and the save semantics — everything needed to call it safely and correctly. Nothing material for correct invocation 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 goes further by tying save:false to the verification workflow and by warning that a domain may resolve to a different company, which changes how the agent should choose the domain vs description parameter. It does not add much beyond the schema for platform/socialHandle.

Input schemas describe structure but not intent. Descriptions should explain 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 (draft/fill in) and resource (a brand/creator profile), and names the output shape ({name, products, logo, …}) plus the downstream consumers plan_ad and generate. It does not explicitly contrast itself with the sibling brand tools (create_brand, update_brand, get_brand), so an agent must infer the 'draft vs persist' distinction from the save parameter.

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

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

Explicit about when to use it (before spending credits on research or renders), what to do when the result looks wrong (re-draft with correct domain or a description, pass save:false until confirmed), and who owns the verification step. This is exactly the when/when-not/alternative guidance the dimension asks for.

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

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

Annotations already declare non-readonly, non-destructive, open-world behavior, but the description adds material context: the source footage is left untouched (nothing re-rendered), the transcription is automatic, and the operation is Paid. It also discloses the return value (served URL of the localized video). Cost and output disclosure go beyond the annotation set.

Agents need to know what a tool does to the 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 differentiating trait (no re-rendering, visuals/timing/edit untouched) before mechanics and cost. Two dense sentences with no padding, and the routing-relevant 'just pass the video and the language' instruction is easy to find.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 states the return is the served URL of the localized video, and annotations cover the safety profile. The only gap is the absence of any routing against similar siblings, but for calling the tool correctly the definition is essentially 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 the schema already documents all four parameters, and the description largely restates them (script auto-read, voice default matching the speaker's register). With the schema doing the heavy lifting, baseline 3 is appropriate; no additional syntax or format detail is added.

Input schemas describe structure but not intent. Descriptions should explain 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 (localize/dub) and resource (a finished video) and explains the mechanism: transcription, translation, re-voicing and lip-sync onto the SAME footage without re-rendering. This distinguishes it from siblings like change_voice (voice only), add_subtitles (text only) and localize_ad (ads rather than finished videos).

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 ('just pass the video and the language') and an important scoping rule for `script` (only to override the auto-transcript). However it never states when to prefer this tool over nearby alternatives such as localize_ad or change_voice, and offers no exclusions, so usage is implied rather than explicit.

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

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

Annotations declare readOnlyHint=false, destructiveHint=true, idempotentHint=false and openWorldHint=true, so safety is partly covered. The description adds genuinely useful context beyond that: the copy is INDEPENDENT (editing/cancelling never touches the original), it is a new post rather than a re-send, and it publishes even where the original already did. It stops short of explaining retry/idempotency implications for repeated calls, which the idempotentHint=false annotation implies.

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

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

Front-loaded with the core action, then override capability, then the at/useQueue mechanism, then independence, then the sibling redirect. Dense and slightly long for a single description, but each clause 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?

For a 21-parameter mutation tool with no output schema, the description covers the operation's semantics, override scope, scheduling options, and the key sibling alternative. Remaining gaps (e.g., what the call returns, behavior on invalid channel/board combinations) are minor against the rich schema and 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 coverage is 76%, so the schema already documents most parameters. The description still adds meaning by enumerating what is copied (caption, media, per-channel captions, title, description, tags, target board/Page/company Page/listing) and clarifying that ANY of them can be overridden in the same call, plus the `at` vs useQueue:true choice. It does not add much beyond the schema for the platform-specific id 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 and resource ('Copy an existing scheduled or already-published post into a NEW queued post') and immediately distinguishes the outcome from a re-send. It also names the sibling it is not (retry_scheduled), so an agent can separate it from reschedule/cancel/retry without opening a schema.

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

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

Gives explicit use cases (re-run a creative, reuse a winning post as a starting point, re-send after publish) and an explicit alternative with its selecting condition: 'To re-fire only the channels that FAILED, use retry_scheduled instead.' When/when-not guidance is present.

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

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

Adds substantial context beyond the annotations: what is preserved (composition, aspect ratio, people, untouched text), that the brand name/website are pinned and the brand logo attached, the semantics of removal:true, the product-label re-print/check behavior with its charging model, and 'One image edit's credits; returns the new image URL.' This is rich disclosure of side effects and costs.

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

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

Front-loaded with purpose and routed alternatives, and every clause carries behavioral information. However the product-photo/label sentence is dense and nested, and the overall block could be tightened; some clauses require re-reading despite earning their 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 6-param, no-output-schema mutation tool, the description covers preservation rules, credit cost, return value (new image URL), and brand/product safety 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 is 3, but the description adds real meaning beyond the schema: removal:true 'so nothing branded is put back' and fixLabel:false disabling product lookup/check/re-print clarify intent beyond the field text. It also frames mask as the precise-region control.

Input schemas describe structure but not intent. Descriptions should explain 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 ('EDIT an existing image in place') plus a plain-language instruction, and closes by naming both sibling alternatives (generate_image, clone_static). An agent can distinguish this from generate_image/clone_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?

Explicit routing: 'For a new image from a prompt use generate_image; to rebuild a competitor's ad for your brand use clone_static.' It also states the conditional for removal:true and fixLabel:false and points to mask usage, giving clear when/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?

Goes well beyond the standard readOnly/openWorld/idempotent/destructive hints: it discloses the preserve-and-lock wrapping behavior, that the quality score is free, that a previewFirstFrame call does not run the paid clip (implying normal runs are paid), and that the reply flags over-reaching edits. This is exactly the cost/behavior context annotations cannot express.

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

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

Front-loaded with the core purpose and examples before the workflow and exclusion details, and every sentence carries usable information for a 13-parameter tool. It is dense to the point of run-on in the previewFirstFrame/previewAt sentence, which costs a point.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 13 params, no output schema, and 3 enums, the description covers what an agent needs: model routing (engine), lighting semantics, the preview/approval loop, rights handling via faceRoute, and expected reply content (quality score plus over-edit flag). Parameter-level detail is safely delegated to a fully documented 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 still adds value beyond the schema by explaining the interaction between previewFirstFrame, previewAt and previewStill ('previewAt picks the second'), and by giving concrete instruction phrasing for the required instruction param. Minor gain, but real.

Input schemas describe structure but not intent. Descriptions should explain 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+mechanism ('EDIT an existing clip from a plain instruction (video-to-video)') and immediately constrains scope: motion/timing/framing/cut stay, only the named thing changes. It names the exact siblings it is not for (post_edit, generate_video, render_ad, dub_video, recast_motion), so an agent can disambiguate without opening any schema.

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

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

Explicit when-not routing to five alternatives, plus positive-fit guidance ('Best on 3-15s clips', 'One change per call holds best'). The preview workflow is given a concrete when-to-use path (previewFirstFrame then call again, ideally with previewStill). 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?

Even though annotations already mark this as non-read-only and non-idempotent, the description adds valuable behavioral detail: a new deck is always created, drive.file scope restricts access to files Hermoso created, expired ad-library links cannot be embedded and are handled gracefully, and the reply reports the count. This goes well beyond the structured annotations.

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

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

The description is front-loaded with the core purpose and then each subsequent sentence adds essential behavior, constraints, edge cases, or prerequisites. There is no filler or tautology; 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?

The description is complete for a tool with no output schema: it states the return value (presentation id + URL), creation semantics, permissions limitations, expired-link handling, and connection prerequisite. Combined with the fully documented input schema, an agent has enough context to invoke this tool correctly.

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

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

The input schema already documents all three parameters with 100% coverage, so the baseline is 3. The description does not add meaningfully to the parameter semantics beyond reinforcing that a collection maps to slides; it mostly discusses tool-level behavior rather than parameter-specific details.

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

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

The description states a specific action and resource: turning a swipefile collection into a Google Slides deck with one slide per ad containing concrete fields. It clearly differentiates itself from related sibling tools like save_to_swipefile or create_doc by emphasizing the export-to-presentation purpose.

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

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

The description gives clear context: this is for presenting to clients/teams, it creates a new deck every time, it cannot add to existing decks, and it requires Google Drive to be connected. It stops short of explicitly naming alternative sibling tools or stating 'use X instead,' so it is not a 5.

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

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

Annotations already declare this a non-readonly write (readOnlyHint=false) with openWorld access and idempotency. The description adds genuinely useful context beyond them: it is FREE/keyless, needs a confident match, and ambiguous lookups save nothing. It does not, however, describe where screens are stored beyond 'durable URLs' or any limits on count.

Agents need to know what a tool does to the 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 keeps each subsequent sentence purposeful (trigger, param default, cost, failure mode, success outcome). Dense but not padded; slightly long versus the minimum 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?

With no output schema, the description carries the full burden and does so: it covers the success result (screens saved with durable, immediately usable URLs) and the failure result (0 screens, nothing saved). Nothing an agent needs to call and interpret it is missing.

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

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

Schema coverage is 100%, so appName (defaults to saved brand name) and brandId (profile id/name from list_brands) are fully documented in the schema. The description only restates the appName default, adding no syntax or format detail beyond schema — baseline 3.

Input schemas describe structure but not intent. Descriptions should explain 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: pulling a brand's REAL App Store screenshots into the workspace brand. It distinguishes itself from siblings by naming the companion tool it feeds (make_template_ad with template:'app-ui-tour'), so an agent can route correctly without opening a schema.

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

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

Gives explicit trigger conditions ('brand has 0-1 app screens on file', 'user asks to pull my app's screenshots') and names the downstream consumer. It also prescribes behavior on failure: relay the 0-screen result plainly rather than retrying with guesses.

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

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

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

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

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

The description is a single, well-structured sentence that front-loads the action, the accepted input, and the resulting output. Every phrase contributes necessary information with no waste.

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

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

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

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description repeats the URL input example and does not mention the optional 'name' parameter or add syntax beyond what the schema provides, making 3 the appropriate baseline.

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

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

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

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

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

The description implies usage by describing the accepted input ('a /generated/… path or any URL'), but it never states when to use this tool versus alternatives or any exclusions. Guidance is present only at an implied level.

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

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

Annotations cover the safety profile (non-read-only, open-world, non-idempotent, non-destructive), and the description adds real behavioral context beyond them: it consumes credits, enforces an allowlist that rejects other paths, and returns raw provider JSON that is large and messy. That is materially useful disclosure for a mutation-adjacent, credit-spending call.

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

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

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

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

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

For a generic passthrough with a 2-param schema, an allowlist constraint, and no output schema, the description supplies everything needed: scope, allowlist, param-name variability, cost, and return-format expectations. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the schema already documents path and params, so the baseline is 3. The description goes further by noting that param names vary per endpoint (handle for profiles, query for keyword searches, subreddit for Reddit) and gives example shapes, which is genuine added meaning.

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

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

The description names a precise verb and resource — 'Generic escape hatch for any ALLOWLISTED long-tail social/web endpoint' — and explicitly frames it against the dedicated search_* siblings. An agent knows exactly what class of call this performs without opening the schema.

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

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

It states when to use it (endpoints the dedicated search_* tools don't cover), when not to (a WARNING says prefer the dedicated search_* tools because output is large/messy), and gives a concrete invocation example. Routing guidance is explicit rather than inferred.

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

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

Annotations already cover readOnly, openWorld, idempotent, destructive hints, and the description adds important behavioral cost structure ('Costs a few credits for the discovery model (no ad-data charge); free inside a new account's first-brand setup') which the agent needs for planning. It also discloses the grounding mechanism ('Claude grounded by web search'). It stops short of describing return format or rate limits, but the credit model is valuable non-structured 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?

It's a single dense sentence but front-loads the core action and mode distinctions before the cost note. Slightly packed, but every clause earns its place by covering purpose, modes, and 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?

For a discovery tool with no output schema and only two params, the description covers purpose, mode selection, grounding source, and the credit/free-first-brand nuance. The main gap is not describing the shape of the returned competitor list, though that's a minor omission given the task is exploratory discovery.

Complex tools with many parameters or behaviors need more documentation. 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 both parameters including the mode enum are fully documented in the schema itself. The description restates the mode options but adds no syntax, format, or validation detail beyond what the schema provides, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ('Discover a brand's competitor / similar / adjacent brands from its domain') and distinguishes the three modes with their distinct outputs, so an agent can tell it apart from siblings like search_meta_ads or pull_competitor_ads without opening the schema.

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

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

It specifies which mode to use ('competitors' default excludes the searched company; 'inspiration' includes it; 'company'), giving practical selection guidance. However it doesn't state when to use this tool versus sibling alternatives like find_creators or competitor_teardown, so it stops short of full when/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?

Beyond the annotations, it discloses cost model (one credit per search call = platforms × queries, plus one per enriched profile), a 20-minute free-repeat caching window, enrichment scope (top 6, default), and the Meta connector prerequisite for marketplace:true — rich behavioral context the annotations do not 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 scan/rank behavior and value, but the single dense paragraph is long and packs workflow, pricing, and marketplace details into run-on clauses. Every element is useful, but structure could be tighter.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 specifies return content (ranked creators with median views, engagement rate, follower counts, and contact info). Combined with cost and workflow context, 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 88%, so the schema documents most params. The description still adds the credit formula tying platforms and queries together, the enrich default/cost, and the marketplace connector dependency, going modestly beyond the schema text.

Input schemas describe structure but not intent. Descriptions should explain 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 (scan/fold/rank) across named platforms and resources, and clearly distinguishes itself from list_creators and search_* siblings by describing aggregation into ranked creators. An agent knows exactly what this returns without opening the schema.

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

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

Explicitly frames the use cases (influencer sourcing, UGC casting, partnership prospecting) and names the downstream alternatives (save_to_swipefile, instagram_profile / fetch_social_data, generate_text, manage_meta_partnership_creator), routing the agent through the workflow.

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

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

The description adds meaningful behavioral detail beyond the annotations: the result is a durable mp3 with start/end positions, and pick selects another candidate from the current TikTok-derived set. This is useful context that the schema and annotations do not provide. No contradiction with the annotations exists.

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

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

The entire description fits into one dense sentence with examples and the key caveat about TikTok's current sounds. There is no filler, and the most important information—what the tool returns and how to invoke it—is front-loaded.

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

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

With no output schema, the description still tells the agent the essential return shape (durable mp3 and placement) and the main input modes. It does not explain no-result or error behavior, but for a simple finder with open-world annotations this is 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 0%, so the description carries the full burden for parameter meaning. It maps query to name/moment, url to link types (TikTok sound, meme-sound page, post, audio file), and pick to alternative-candidate selection. It could be more precise about pick's numbering and whether parameters are mutually exclusive, but it compensates well for the bare schema.

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

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

The description states exactly what find_sound does: find a sound for an edit by name, moment, or link, and return a durable mp3 plus its start/end placement. It goes beyond the title and distinguishes this tool from generic TikTok search or music-generation siblings by specifying the output and the three lookup routes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 intended use case is clear: an editor needing a sound by name, described moment, or source link. The description also notes that named/described sounds are based on what TikTok currently uses, which helps the agent understand the data source. It does not explicitly name alternative sibling tools or state when not to use it, so it stops short of a 5.

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

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

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

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

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

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

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

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

There is no output schema, but the description compensates by stating exactly what each returned row contains (parameters, credit cost, health). It also covers the critical next step (call_tool) and the onlyHealthy filter. For a discovery tool with optional parameters, this is complete context for an agent to use it correctly.

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

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

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

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

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

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

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

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

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

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

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

Despite having annotations, the description adds substantial behavioral detail beyond them: 'no AI model, ~30s, a couple of credits', the exact compositing behavior of pills, the anti-AI intent of grain, and crucially 'Returns a NEW video; the original is untouched' which reinforces destructiveHint=false. This is exactly the extra 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?

The core action is front-loaded in the first clause, and every sentence carries useful information about modes, cost, and return behavior. It is dense and slightly overloaded with em-dashes and parentheticals, and the char-limit repetition duplicates the schema, so it is not maximally tight.

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

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

With no output schema, the description correctly carries the return contract ('Returns a NEW video; the original is untouched') plus cost, runtime, and the two operating modes. For a 7-parameter tool with one required field, an agent has everything needed 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%, so the baseline is 3, but the description meaningfully enriches semantics: it explains what pills=true composites (header pill, brand-accent sub-pill, cascading green-check proof pills), that grain applies a subtle camera-grain finish, and that the caller authors the copy with real (never fabricated) benefits. It repeats the char limits already in the schema, which limits it below 5.

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

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

The description states a precise verb and resource ('Post-process an EXISTING rendered video (its served mp4 URL)') and clearly distinguishes this finishing step from generation/editing siblings by naming the two passes it performs (reviewer pills, film-grain). An agent can tell it apart from generate_video, edit_video, or upscale_video without opening the schema.

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

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

It gives clear usage context: the input must be an already-rendered video URL from a previous render/job, and it explains the two modes ('pills=true ... grain=true ... works alone or with pills'). However, it never explicitly names an alternative tool or states when NOT to use it (e.g. versus edit_video or upscale_video), so routing is left partly 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: billing model ('bills only the replacement clip's seconds (~1/3 of a full render)'), preservation guarantee ('the rest of the video and ALL audio stay byte-identical'), and the harm mode of a bad window ('a video-only splice under speech breaks lip-sync'). Annotations only declare non-readonly/non-idempotent/open-world; the description carries the real behavioral burden.

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

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

Dense but front-loaded and every clause earns its place: purpose first, then routing rationale, then the dialogue warning. Slightly packed into one long flow, but no wasted sentences.

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

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

For a mutating, non-idempotent, open-world tool with no output schema and 7 params, the description covers cost, side effects, scope limits, and the critical failure mode. 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 schema: the 1.5-8s window constraint, what dryRun reserves (exact credits), and the lip-sync rationale that makes speechWindows a correctness requirement rather than a hint. Adds genuine value over the field descriptions.

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

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

States a specific verb+resource+scope: 'Surgically re-render ONE time window (1.5-8s) of an existing rendered video and splice it back on the VIDEO TRACK ONLY.' The scope (single window, video track only, audio untouched) distinguishes it sharply from full-render siblings like render_ad or edit_video.

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

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

Gives an explicit when ('one beat/shot is broken') including an example utterance, explains the alternative it displaces ('a full re-render would waste the parts that worked'), and adds an explicit exclusion ('Do NOT pick a window covering spoken dialogue') with a mitigation ('pass speechWindows').

Agents often have multiple tools that could apply. Explicit usage 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's added value is the cross-device delete behavior (it won't come back) and the re-creatable/reversible nature that justifies skipping confirmation. That is genuine context beyond the annotation flags, though it doesn't cover error cases (e.g., unknown id) or response behavior.

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

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

Three tight sentences with the action and key front-loaded, then persistence behavior, then the confirmation rationale. 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 single-parameter destructive tool with no output schema, the description covers action, key source, durability, and reversibility. Minor gap: no mention of failure behavior for an invalid or already-deleted id.

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

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

Schema coverage is 100% and the id parameter is already documented as coming from list_memory, so the description mostly restates the schema. The optional brand parameter ('this call only') is never addressed in the description.

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

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

States a specific verb (Delete) and resource (a saved Memory item) plus the lookup key (id from list_memory), which cleanly separates it from siblings like list_memory, remember, and tidy_memory.

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

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

Gives clear context: the id comes from list_memory, and it explicitly says no confirmation is needed because the action is minor and re-creatable. It does not name when to prefer tidy_memory or other memory-management siblings, but the routing for this tool 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?

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=true, and the description adds the useful 'never gated' behavioral fact plus the helpful defaults (all three actions on the first tab, how to skip each). However, it frames itself as non-destructive ('Changes no cell VALUE') without warning that applying bold/auto-resize can overwrite existing cell formatting, which sits in tension with destructiveHint=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?