Hermoso

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

Annotations indicate read-only and open-world. Description adds cost behavior and output structure details, no contradictions.

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

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

Two sentences, front-loaded with purpose and output details, no unnecessary 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?

Given single parameter, no output schema, description explains output contents and cost, fully covering the tool's purpose and 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?

Only one parameter with full schema coverage. Description repeats the allowed URL types, adding slight clarity but not significant value beyond the schema.

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

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

The description clearly states the tool breaks a video ad into its structure, specifying verbatim transcript, beat list, duration, and frame timestamps. It distinguishes from sibling tools by focusing on structural analysis of a single video.

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

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

Explicitly says to use for studying reference/competitor ads before remixing. Provides cost context but does not offer explicit alternatives or when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true. Description adds 'Read-only, free' and notes admin rights, providing behavioral context beyond annotations. 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?

Single sentence with a clear, front-loaded list of what it shows, followed by usage guidance. 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?

No output schema, so description explains return values by listing the displayed properties. Sufficient for a simple read-only tool with zero parameters.

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

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

No parameters exist; schema coverage is 100%. Baseline for zero params is 4. Description does not need to add parameter info but effectively lists output content.

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

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

The description clearly states it shows billing at a glance with specific items like plan, credit balance, auto-reload, card on file, and admin rights. It distinguishes itself from sibling tools like upgrade_plan and set_auto_reload by being read-only and a prerequisite check.

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

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

Explicitly states when to use: 'Call it before upgrade_plan / set_auto_reload to know what's possible — members have read-only billing.' This provides clear context and 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 that nothing is charged until the human pays, credits land instantly upon payment, and agents never spend money directly. This goes beyond the readOnlyHint and openWorldHint annotations, explaining the non-destructive nature and the secure payment flow.

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

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

All sentences are informative, but the description could be slightly more concise (e.g., 'Call with no argument to list packs. Call with pack id to get checkout URL.'). Still, it is well-structured and front-loaded with the core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 no output schema, the description explains both possible return values (list of packs or Stripe URL) and the overall flow. It covers prerequisites, process, and outcome, making it self-contained for the agent.

Complex tools with many parameters or behaviors need more documentation. 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%. The description explains the effect of omitting pack (list packs) vs. providing it (get checkout URL), adding context that the schema alone lacks (e.g., 'omit to list the available packs first').

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

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

The description clearly states the tool generates a checkout link for credit packs. It distinguishes itself from sibling billing tools by focusing on one-time credit purchases via Stripe, with explicit mention of pack vs subscription differentiation.

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

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

Provides explicit instructions: call without arguments to list packs, call with 'pack' to get checkout URL. Advises handing URL to human and clarifies that subscriptions are handled elsewhere (Settings → Billing). This tells the agent exactly when and how to use the tool.

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

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

Describes what is preserved (performance, lip-sync, background sound) and output format (served URL), adding value beyond annotations. No contradictions.

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

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

Three efficient sentences covering purpose, usage, cost, and output; 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?

Complete for a simple 2-param tool with no output schema; explains output, cost, and sibling distinction.

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

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

Schema coverage 100%, baseline 3. Description adds voice examples ('Aria', 'George') and default behavior, adding value beyond 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?

Clearly states verb 'Swap' and resource 'narration of a finished video', distinguishes from sibling 'dub_video'.

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

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

Explicitly states when to use ('user likes the video but wants a different narrator voice') and when not ('use dub_video only for language translation'), plus mentions 'Paid'.

Agents often have multiple tools that could apply. Explicit usage 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 readOnlyHint=true and destructiveHint=false. The description reinforces this by stating it is a check, never changes creative, and pulls live policy pages. It adds context about the verdict format and that it is a 1-credit operation, enhancing transparency beyond 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 main purpose and then provides details. It is reasonably concise, though could be slightly trimmed. Every sentence adds value, conveying key information 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?

For a tool with 4 parameters and no output schema, the description adequately explains the return format (verdict with quotes and rewrites), credit cost, and use cases. It does not cover error conditions but is otherwise complete for its complexity.

Complex tools with many parameters or behaviors need more documentation. 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 covers all 4 parameters with descriptions. The tool description adds that the category parameter helps pick relevant policy pages, providing some extra context. However, the baseline is 3 since schema coverage is 100% and the description does not significantly enhance parameter understanding.

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

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

The description clearly states it is a pre-flight check of ad copy against Meta's live advertising standards, returning a verdict with policy quotes and rewrites. It distinguishes itself from siblings like score_ad by emphasizing it is a check, not an edit, and specifically targets policy compliance.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 advises using the tool before running ads and highlights regulated-adjacent categories where it is especially useful. It does not explicitly mention when not to use it or compare to alternative tools, but provides clear context for its application.

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

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

Describes behavioral traits beyond annotations: credit costs (0 when passing ads, 1-2 when auto-pulling), LLM token usage, auto-tailoring to saved brand. No contradiction with annotations (readOnlyHint=false, destructiveHint=false).

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

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

Description is well-structured and front-loaded with key outputs, though slightly verbose. Each sentence adds value, using capitalization for emphasis (MIX, THEMES, etc.) and separating contract details clearly.

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

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

Given no output schema, the description provides a comprehensive list of what the tool produces but lacks explicit return structure. It explains inputs, costs, and tailoring, but could further detail how the saved brand influences white space/counter-plays.

Complex tools with many parameters or behaviors need more documentation. 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 description adds significant meaning: explains the 'ads' parameter's source (from pull_competitor_ads / search_meta_ads) and behavior when omitted, clarifies 'competitor.domain' sharpens auto-pull page match, and notes 'language' defaults to English.

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

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

The description clearly states the tool's purpose with a specific verb ('Tear...down') and resource ('competitor's ad strategy'), listing the exact outputs (hook MIX, themes, white space, counter-plays, avoid territories). It distinguishes from sibling tool 'pull_competitor_ads' which only pulls ads, not tear down.

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

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

Provides explicit guidance on when to use this tool versus alternatives: supply ads from prior pulls to avoid credit cost, or omit to auto-pull (costs credits). Also mentions auto-tailoring to saved brand, giving clear context for usage decisions.

Agents often have multiple tools that could apply. Explicit usage 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 important behavioral traits beyond annotations: 0 credits cost, the possibility of wrong company from domains, and the need for manual verification. Aligns with annotations (openWorldHint) and adds critical workflow 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?

Description is well-structured with purpose first, then important caveats and parameter behavior. Slightly verbose but every sentence contributes; front-loading the core purpose aids quick understanding.

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

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

Covers return format, parameter behavior, cost, and a key edge case (domain mis-resolution). Lacks explicit error handling or rate hints but sufficient given optional parameters and no output schema.

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

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

Schema coverage is high (80%); description adds meaningful context for 'save' (default behavior and override logic) and warns about domain resolution pitfalls. Does not elaborate on platform or socialHandle beyond schema, but adds value overall.

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

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

The description clearly states the tool's purpose: 'Onboard a brand profile' from various inputs into a structured object for downstream use. It distinguishes from siblings like 'get_brand' and 'list_brands' by emphasizing creation/onboarding 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?

Explicit guidance on when to use and precautions: warns about domain mis-resolution, advises verifying the returned name before spending credits, explains save parameter behavior (default overwrite logic), and notes that the caller owns the verification check.

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

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

Annotations indicate it is not read-only (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds transparency by noting the tool is paid, returns a served URL, and involves re-voicing and re-muxing. It discloses key behavioral aspects beyond annotations, though the exact mutating effect (e.g., whether the original is overwritten) is not detailed.

Agents need to know what a tool does to the 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 efficiently conveys the core action, process details, cost implication, and output. Every phrase serves a purpose, and there is no unnecessary text. It is front-loaded with the primary action and expands with necessary context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 moderate complexity (3 parameters, no output schema), the description adequately covers what the tool does, its input (finished video ad), process (translated script, re-voiced, re-muxed), and output (served URL). It mentions payment but could be slightly improved by clarifying whether the original video is preserved or replaced. Overall, it is sufficiently complete for an agent to understand the tool's purpose and outcome.

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

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

Schema coverage is 100%, so the input schema already describes all three parameters adequately. The description does not add new parameter-level meaning beyond what the schema provides; the only added context is that the tool is for finished videos, which is implied in the description but not attached to specific parameters. Thus, the description adds no value to parameter understanding beyond schema.

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

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

The description clearly states the specific verb 'Remake a finished video ad's voiceover in another language' and identifies the resource as a finished video ad. It details the process (translated script, re-voiced, re-muxed), which distinguishes it from siblings like 'change_voice' that likely handle simple voice replacement without language 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?

The description implies the tool is for finished videos ('finished video ad') and mentions it is paid, but it does not explicitly state when to use it vs alternatives (e.g., 'change_voice' for same-language voice changes) or when not to use it. The guidance is minimal, providing no exclusions or context for choosing among siblings.

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

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

Annotations already indicate readOnlyHint=true, so the description does not need to emphasize safety. It adds that the tool returns a clickable absolute URL and a direct download URL, but does not disclose any failure modes or rate limits. The addition is minimal but consistent 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 a single, fluff-free sentence that front-loads the purpose and outputs. Every word adds value, and there is no wasted 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?

The description explains the core functionality and output, but does not cover error handling, input validation, or the exact structure of the returned URLs. Given the absence of an output schema, more detail on the return format would improve completeness.

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

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

Schema description coverage is 50% (only url has schema description). The main description repeats the url schema description ('a /generated/… path or any URL') but adds no new meaning for the 'url' parameter. The 'name' parameter has no schema description and the main description does not address it at all, leaving it 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?

The description uses a specific verb 'Resolve' and explicitly names the resource 'generated asset reference (a /generated/… path or any URL)' and the outputs 'clickable absolute URL + a direct download URL'. This clearly distinguishes it from sibling tools which focus on video, ads, billing, etc.

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

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

The description clearly states what the tool does, implying it should be used when you have an asset reference that needs conversion to usable URLs. However, it does not provide explicit when-not-to-use guidance or mention alternatives, which are not needed as no sibling tool offers the same functionality.

Agents often have multiple tools that could apply. Explicit usage 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 readOnlyHint and openWorldHint. The description adds that Claude is grounded by web search and that the tool uses 0 ScrapeCreators credits, which provides useful behavioral context beyond annotations. No contradictions.

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

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

Two sentences with no wasted words. The first sentence states the core purpose and grounding; the second explains modes and credits. Front-loaded and efficient.

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

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

Covers purpose, modes, credits, and grounding. Missing information about the return format or examples, but given no output schema, this is acceptable. Could be more complete by hinting at the output structure.

Complex tools with many parameters or behaviors need more documentation. 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 description adds significant meaning beyond the schema: it explains what each mode does (competitors excludes the company, inspiration includes it, company is for the brand itself) and notes the default. The schema only provides an enum and a generic domain description.

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

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

The description clearly states the tool discovers competitor/similar/adjacent brands from a domain using web search. It distinguishes from siblings like competitor_teardown and pull_competitor_ads by focusing on brand discovery rather than analysis or ad retrieval.

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

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

The description explains the three modes and their defaults but does not explicitly state when to use this tool over siblings like competitor_teardown or pull_competitor_ads. Usage context is implied but not made explicit.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description explains key behaviors: it returns a new video without altering the original, applies specific visual effects (pills with character limits, grain), and mentions performance (no AI model, ~30s). 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 well-structured, starting with the overall purpose, then detailing pills and grain, and ending with the return value. It is detailed but not overly verbose; could be slightly tightened but remains clear and informative.

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

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

Given the complexity (7 parameters, no output schema), the description covers the tool's functionality, parameter effects, and result (returns new video). It lacks explicit error handling or prerequisites (e.g., video must be from a previous render), but is largely 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?

The description adds significant meaning beyond the input schema: it explains the purpose and constraints of each pill (header ≤40 chars, sub ≤34, points ≤44 each), the effect of 'grain' (makes AI renders look phone-shot), and relationships (header required when pills is on). Schema coverage is 100% but description enriches understanding.

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

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

The description clearly states the tool's purpose: post-process an existing rendered video with pills (reviewer finish) and/or film-grain. It uses specific verbs ('post-process', 'composites', 'applies') and distinguishes from other tools by focusing on finishing, not generation.

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

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

The description provides clear context for when to use the tool (on an existing rendered video, no AI model, ~30s, a couple of credits). It does not explicitly exclude alternatives like 'upscale_video' or 'reframe_video', but the parameter-level guidance is detailed (e.g., 'pills=true default', 'grain=false').

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

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

The description discloses key behaviors: the tool modifies only the video track, leaves audio untouched, and bills only the replacement clip's seconds. This adds value beyond annotations (readOnlyHint=false, destructiveHint=false). However, it does not describe what the tool returns (output), which is a gap given no output schema.

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

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

The description is three sentences, front-loading the core action and then providing usage guidance. Every sentence adds value with no redundancy or filler.

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

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

The description covers usage scenarios, constraints, and billing, but misses the return value (output) entirely. Given the tool's complexity (6 parameters, mutation, billing side effects) and missing output schema, the description is not fully complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description reiterates parameter purposes but adds only minor context (e.g., window size 1.5-8s, using speechWindows to avoid overlap). This provides marginal additional meaning beyond the schema.

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

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

The description clearly identifies the tool as a surgical re-render and splice of a time window on the video track only, distinguishing it from a full re-render. The verb 'fix' combined with 'beat' and the detailed action 're-render ONE time window... splice it back' makes the purpose very specific and distinct from sibling tools like 'render_ad' or 'generate_video'.

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

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

The description explicitly states when to use this tool: when a single beat/shot is broken and a full re-render would waste resources. It provides a clear when-not: do not pick a window covering spoken dialogue, and directs the agent to pass 'speechWindows' to enforce this constraint. This level of guidance is exceptional.

Agents often have multiple tools that could apply. Explicit usage 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 blocking behavior and credit consumption, which adds value beyond annotations (readOnlyHint=false, destructiveHint=false). However, it lacks information about return value or side effects, which is important for a mutation tool with no output schema.

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

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

Three concise sentences with no fluff. The first sentence immediately states the purpose, followed by blocking duration and requirements. Excellent front-loading and efficient use of 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?

Given the tool has no output schema, the description should explain what the tool returns (e.g., video URL). It covers blocking time and credits but omits output format, making it slightly incomplete for an agent to fully anticipate 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 description adds minimal extra meaning. It implicitly maps 'image' and 'script' from the description but does not elaborate on voice or resolution beyond the schema 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 clearly states 'Render a TALKING-AVATAR / creator lip-sync clip', using a specific verb and resource. It distinguishes itself from siblings like generate_video or dub_video by specifying lip-sync from image + script.

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

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

Includes practical usage context: blocks for 1-3 minutes, requires avatar capability, and spends credits. Does not explicitly state when not to use or offer alternatives, but the context is sufficient for an agent to 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 indicate the tool is not read-only and not destructive. The description adds that it is fast and spends credits, which complements the annotations. No contradictions.

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

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

Two sentences with a parenthetical, front-loaded with the main action. Every sentence adds value, no redundancy.

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

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

Given 6 parameters, annotations, and no output schema, the description covers key behaviors (compositing, model selection, speed, cost) and return value (URL). Lacks details on imageSize/aspectRatio, but overall sufficient.

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

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

Schema description coverage is 83%, so baseline is 3. The description adds context for refImages (compositing) and model (catalog id), but does not cover imageSize or aspectRatio. Value is adequate but not exceptional.

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

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

The description clearly states it renders a finished ad image and returns a URL. The verb 'render' and resource 'ad IMAGE' are specific, and the mention of refImages for compositing distinguishes it from sibling tools like generate_video.

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

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

The description explains when to use refImages and model parameters, but does not explicitly contrast with alternatives like render_ad or generate_avatar. It provides context on speed and credit cost, which aids usage decisions.

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

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

Description adds value beyond annotations by disclosing credit cost, default model behavior, and the fact it is prompt-only. Annotations indicate non-read-only, non-destructive, which aligns.

Agents need to know what a tool does to the 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 key purpose, examples, and relevant clarifications. No unnecessary 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?

Given no output schema, description could mention return format, but the context (text generation) and sibling disambiguation make it fairly complete. Pricing and model selection are covered.

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

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

Schema covers both parameters fully (100% description coverage). Description adds slight extra context about omitting model for default, but does not significantly enhance understanding beyond schema.

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

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

The description clearly states it is for raw text generation using a catalog of writing models, and explicitly contrasts with ad assembly tools (plan_ad, render_ad), making its purpose distinct.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 clear context for when to use (prompt-only text generation) and distinguishes from siblings. Mentions pricing but lacks explicit 'when not to use' exclusions beyond ad assembly.

Agents often have multiple tools that could apply. Explicit usage 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=false, openWorldHint=true. The description adds that renders take 1-3 minutes, credits are spent, and explains edit behavior (inherits source canvas and length). It does not detail potential side effects beyond credit consumption, but given annotations, the transparency 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?

The description is efficiently structured: starts with main purpose, then contrasts with sibling, then explains key constraints, then lists parameter roles. Every sentence adds value, no fluff.

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

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

With 10 parameters, no output schema, and 90% schema coverage, the description covers essential behavioral aspects: generation vs edit, duration limits, credit cost, and rendering time. It is complete enough for effective tool selection and 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 90%, so the schema already describes most parameters. The description adds meaningful context: refImage anchors opening frame, ttsScript adds voiceover, refVideo edit inherits source length, and durationSeconds must be one of the model's durations. This adds value beyond the schema.

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

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

The description clearly states it 'Render[s] a RAW video clip from your own prompt and return[s] its served mp4 URL.' It distinguishes itself from the sibling 'render_ad' tool by specifying that tool is for finished brand ads, while this is for raw/experimental clips or precise manual control.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 guidance: 'For finished brand ADS prefer render_ad... use this for raw/experimental clips or precise manual control.' Also warns that durationSeconds must match model durations from hermoso_capabilities, and explains when to use refVideo for editing vs generating from scratch.

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

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

Annotations already provide non-read-only, non-destructive, open-world hints. Description adds cost model (credits by length, ≤900 chars), return type (MP3 URL), and parameter effects. Does not address idempotency or state changes beyond credit consumption, but open-world hint covers external dependencies.

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

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

Single dense paragraph, front-loaded with purpose and return value, followed by usage guidelines and parameter details. No redundant 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 3-parameter tool with no output schema, the description covers all necessary context: return type (MP3 URL), cost, character limit, parameter specifics, and sibling differentiation. Nothing 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 covers all 3 parameters with 100% description coverage. Description adds value by providing example values for voice ('Aria', 'George', 'stokie_en'), listing engine options, and cross-referencing hermoso_capabilities for further details. Baseline 3 uplifted to 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?

Clearly states it's a text-to-speech tool that returns an MP3 URL. Differentiates itself from sibling tools (render_ad, generate_video, change_voice) by specifying it's for standalone voiceovers, not adding audio to video.

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

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

Explicitly states when to use (standalone voiceover/narration) and when not to (adding audio to video, which is handled by render_ad and generate_video; re-voicing by change_voice). Also directs users to hermoso_capabilities for voice/engine options.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so description adds value by noting '0 credits' and behavioral context of returning saved knowledge. Could elaborate on learned memory structure but sufficient.

Agents need to know what a tool does to the 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 packed sentences, no filler. First sentence defines purpose and scope, second provides actionable workflow guidance. Excellent efficiency.

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

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

Given no output schema and zero parameters, description fully covers what an agent needs: what it returns (brand profile + learned memory), how to use result (check hasBrand), and relationship to other tools (draft_brand). 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?

No parameters; description explains what the tool returns (brand profile content). With 100% schema coverage and 0 params, baseline is 4, and description adds meaningful context about output nature.

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

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

Description clearly states verb 'get' and resource 'brand profile', including specific contents (products, logos, palette, positioning) and learned memory. It distinguishes from siblings like draft_brand and use_brand by positioning this as the first call.

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

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

Explicitly instructs to call this first and provides conditional logic: if hasBrand is true, omit brand elsewhere; if false, onboard with draft_brand. No ambiguity in when to use.

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

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

Discloses that tool is a read-only poll (consistent with annotations), returns status, progress, and URL. Also explains the expected polling pattern and normal delay, which annotations (readOnlyHint) do not 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?

Two sentences, no fluff. First sentence covers purpose and return values, second covers usage guidance. Front-loaded with essential 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 no output schema, the description fully explains return values and polling behavior. Comprehensive for a simple poll tool.

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

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

Schema coverage is 100% with clear description for the single parameter 'id'. The description does not add extra meaning beyond the schema, but it is adequate.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Poll') and resource ('render job'), clearly stating the action and return values. It distinguishes from siblings like 'list_jobs' by focusing on a single job status check.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 guidance on when to use: 'keep calling this until done/error without asking the user — several calls is normal, not a stall.' Provides clear polling behavior and expected latency.

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

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

Annotations already declare readOnlyHint=true, so the 'Read-only, free' tag aligns and adds minimal extra. The description explains the content loaded (SKILL.md) and how to use it, but does not disclose additional behavioral traits like response format or limitations. With annotations covering safety, a 3 is appropriate.

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

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

The description is two sentences with no wasted words. It front-loads the purpose and provides immediate actionable guidance. Every sentence earns its place.

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

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

For a single-parameter, read-only tool with no output schema, the description is complete. It explains what is loaded, how to use it, and the read-only nature. The agent has enough context to invoke and use the tool correctly.

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

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

Schema coverage is 100%, and the description reiterates 'by name (from list_skills)', adding no new meaning beyond the schema's description. Baseline 3 is correct as the schema already documents the parameter well.

Input schemas describe structure but not intent. Descriptions should explain 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 'Load a bundled skill’s full SKILL.md workflow instructions by name (from list_skills)', using a specific verb and resource. It distinguishes from sibling tools by referencing list_skills and explaining the follow-up action, ensuring the agent knows exactly 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 clear context ('from list_skills') and instructs to 'Follow the loaded instructions to run that workflow', implying when to use. It does not explicitly list when not to use or provide alternative tools, but the context is sufficient for proper usage.

Agents often have multiple tools that could apply. Explicit usage 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 confirms it is read-only and free, matching the readOnlyHint annotation. It adds detail about the return contents (model IDs, costs, flags) beyond annotations.

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

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

Two concise sentences, front-loaded with purpose. 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 zero-parameter tool without output schema, the description covers the intent and return content adequately. It mentions specific flags and fields, though format is not detailed.

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

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

No parameters, so baseline is 4. The description adds value by explaining what the tool returns, compensating for the lack of output schema.

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

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

The description clearly states it probes capabilities of the Hermoso account, listing specific fields like model IDs, costs, aspect ratios, etc. It distinguishes itself from sibling generation tools by being a probe.

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

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

Explicitly says 'Call this FIRST' to get valid model IDs and costs before generation. Provides clear context for when to use, though no explicit when-not-to-use or alternatives.

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

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

Annotations declare readOnlyHint=true, and the description confirms a read operation. It adds details about what is returned (balance, session usage, recent calls). No contradictions.

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

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

Two concise sentences with zero waste. First sentence states output, second provides usage guidance. Well 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?

No output schema, but description enumerates return fields. Lacks detail on 'recent priced calls' (e.g., count, time range). Still fairly complete given no parameters.

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

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

No parameters in schema, so baseline is 4. The description compensates by listing return values, which adds meaning beyond the empty schema.

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

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

The description clearly states the purpose: returning account credit balance, session credits used, and recent priced calls. It uses specific verbs ('Return') and resource ('account credit'), and distinguishes from siblings by suggesting usage before paid generation.

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

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

Provides explicit context: 'Check before kicking off paid generation.' This tells the agent when to use it. No explicit exclusions or alternatives, but the context is clear.

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

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

Annotations already declare readOnlyHint=true. Description adds 'Read-only, free' reinforcing safety and cost, and specifies output fields (id, name, current brand), providing behavioral context beyond annotations. 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?

Two sentences, zero wasted words. Front-loaded with main purpose. Highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 zero parameters and no output schema, description adequately covers core function and use case. Mentions output format and multi-brand scenario. Lacks details on limits or pagination, but sufficient for this simple 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?

No parameters exist; schema coverage is trivially 100%. Description adds no parameter info as none needed. Baseline of 4 is appropriate.

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

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

Description clearly states verb 'List' and resource 'every brand on this account' with specific output fields (id + name) and identifies which brand the connection acts on. Distinguishes from siblings like use_brand and get_brand by specifying the action and context.

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

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

Provides explicit guidance: 'Multi-brand accounts: call this, then use_brand to switch.' This tells the agent when to use it (multi-brand accounts) and the next step. However, it does not explicitly state when not to use it or list alternatives beyond use_brand.

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

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

Annotations already mark it as read-only. The description adds that it returns 'most recent' jobs and count of running ones, but no additional behavioral traits (e.g., pagination, sorting) are disclosed. With annotations covering safety, this is adequate but not enhanced.

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

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

A single, well-structured sentence that front-loads the purpose and usage context. 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 no-parameter listing tool, the description adequately conveys what is returned (recent jobs and running count). Without an output schema, it gives a sufficient mental model for the agent to understand the result format. Missing details like ordering or limits are minor.

Complex tools with many parameters or behaviors need more documentation. 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 zero parameters and 100% schema coverage, the description does not need to add parameter info. The baseline is 4, and the description appropriately omits param details since none exist.

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

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

The description clearly states the tool lists recent render jobs and current running count. It uses specific verb 'list' and resource 'render jobs', and distinguishes itself from sibling 'get_job' by indicating it returns multiple items and counts.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 hints at usage for reporting or resuming in-flight work, but lacks explicit when-not-to-use or alternatives like 'get_job' for individual jobs. Implied context is present but not fully exclusions.

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

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

Annotations already indicate read-only, no destruction. Description adds that it surfaces photos from other creations, which is a behavioral trait beyond annotations. 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?

Description is informative but slightly verbose with parentheticals. Front-loads main purpose. Every sentence adds value, but could be tightened.

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

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

No output schema, but description explains return values (url + label). Covers scope (library, screens, locked creations). Complete for a simple listing tool with one optional param.

Complex tools with many parameters or behaviors need more documentation. 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 covers brandId with description; tool description adds that passing brandId switches the active brand like use_brand, providing extra context beyond schema.

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

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

The description clearly states the tool lists product photos saved in the workspace, including from brand library and app-store screens. It distinguishes from sibling 'set_product_image' by advising to call this first. Verb+resource+scope are specific.

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

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

Explicitly suggests calling before set_product_image and explains that passing brandId targets a specific brand and switches the active brand. Lacks explicit when-not-to-use instructions, but context is clear.

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

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

Annotations already declare 'readOnlyHint: true' and 'openWorldHint: false'. The description adds 'Read-only, free,' which reinforces the annotation but does not provide additional behavioral context beyond what is already structured. It does not contradict annotations.

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

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

Two concise sentences that front-load the purpose, define what skills are, mention the relevant sibling tool, and state properties. No unnecessary 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 no parameters, no output schema, and annotations covering read-only behavior, the description is fully adequate. It explains what is listed and how to proceed with loading a skill, meeting all informational needs for this simple list operation.

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

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

The input schema has no parameters, so the description does not need to add parameter-level meaning. The description compensates by explaining the nature of the returned items (skills as workflow instructions). Baseline 4 applies for zero parameters.

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

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

The description clearly states it lists 'bundled Hermoso SKILLS' and distinguishes them as multi-step workflow instructions that orchestrate other tools, plus in-app strategy skills and creative recipes. It explicitly differentiates from the sibling tool 'get_skill', which loads a bundle.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 user to call 'get_skill' to load a bundle, providing clear guidance on when to use this tool versus its sibling. It also states 'Read-only, free,' indicating it is safe to call without restrictions. No explicit 'when not to use' is provided, but the alternative is well-defined.

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

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

Annotations indicate readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description adds valuable behavioral context: it takes ~30 seconds, costs a couple of credits, mentions image localization, and a voiceover charge for myth-vs-fact. This goes beyond the annotations' minimal signal.

Agents need to know what a tool does to the 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 very long but front-loads the core purpose, speed, and cost. It is structured with template details in a bullet-like format. However, the sheer length (several hundred words) may hinder quick parsing by an AI agent, earning a mid-range score.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 thoroughly covers input configuration for all templates and notes credit costs. However, it lacks explicit output details (e.g., format, file type, how to access the rendered ad) despite the absence of an output schema. This gap reduces completeness.

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

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

The input schema has one parameter config with a brief description. The tool's description extensively documents config fields for each of the 12+ templates, including required fields and structure. This adds enormous meaning beyond the schema's generic description.

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

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

The description clearly states the tool's function: 'Render a NATIVE-STYLE TEMPLATE ad from pure HTML — no AI video/image model in the loop'. It distinguishes from siblings like generate_image and generate_video by emphasizing speed, cost, and native-style output. The verb 'render' and resource 'template ad' are specific.

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

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

The description says 'Perfect for native-feel social ads at volume' and provides content authoring guidance (short, casual, believable). However, it does not explicitly state when NOT to use this tool or compare it to alternatives like render_ad. Usage context is implied but not fully delineated.

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

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

Beyond annotations (readOnly, openWorld), description adds credit/token consumption and brand-switching side effect, which are valuable. No contradictions.

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

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

Dense and informative but somewhat run-on; could use better structure (e.g., bullet points) for readability. Still every sentence adds value.

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

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

No output schema, but description fully explains return format (ranked angle bank with tags, quotes, scores, hooks). Also covers side effects and prerequisites.

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

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

Schema coverage 100% but description adds crucial context: omission uses active brand, and using brandId switches active brand like use_brand tool.

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

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

Specifically states it mines ad angles from real customer language, gathering from multiple sources. Clearly distinguishes from sibling 'competitor_teardown' by name and 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?

Explicitly tells when to use brandId parameter and when to omit, and directs to competitor_teardown for competitor analysis. Also mentions credit/token costs.

Agents often have multiple tools that could apply. Explicit usage 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 open world behavior (uses workspace’s saved brand), cost (LLM tokens, no credits), and notes it does not render. This adds valuable context beyond annotations (openWorldHint=true).

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

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

Concise and front-loaded: first sentence captures essence. Every sentence adds value without redundancy. Role-appropriate tone ('Creative director').

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

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

Adequately describes outputs (copy variants, image prompt, storyboard, recipe, model ids) and chaining instructions. No output schema, but description covers key behavioral aspects. Could briefly mention expected response structure.

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

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

Adds meaningful detail beyond schema for multiple parameters (brand can be object, format enum, recipe forces archetype, reference remix). Schema coverage is 83%; the only undocumented parameter 'language' has no description but is minor.

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

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

Description clearly states it transforms a brand/product/brief into a finished ad concept including copy variants and image/video prompts, explicitly distinguishing itself from rendering tools like generate_image/generate_video.

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

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

Provides guidance on when to use (creative director role) and what to chain after (generate_image/generate_video). Mentions alternatives like draft_brand for onboarding a new brand. Could be more explicit about when not to use.

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

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

Annotations indicate openWorldHint=true and destructiveHint=false; the description adds context that this is an LLM planning tool that relies on downstream tools (generate_image, score_ad) and does not perform rendering itself, which helps an agent understand its role.

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

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

The description is two sentences with no wasted words, front-loading the core purpose and key behavioral details.

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

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

Given the complexity (generating multiple variations), the description explains the tool's role, inputs, and interactions with other tools. However, it does not specify the output format or provide an example, which could improve completeness.

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

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

The description adds minimal parameter meaning beyond the schema (e.g., 'N distinct ad angles' relates to the 'count' parameter). Schema coverage is 75%, with the 'language' parameter lacking a description; the tool description does not compensate for that gap.

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

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

The description uses specific verbs ('Fan a brief into N DISTINCT ad angles') and resource ('ad angles'), clearly distinguishing the tool from siblings like 'plan_ad' or 'mine_angles' by highlighting its uniqueness (multiple angles, each with headline and visual brief).

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

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

The description states when to use this tool ('Fan a brief into N DISTINCT ad angles') and what it does not do ('renders nothing itself'), but does not explicitly list alternative tools or scenarios where other tools are preferred.

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

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

Annotations already indicate readOnlyHint and openWorldHint. The description adds valuable behavioral details: deduped, sorted, right page resolved, and credit consumption. No contradiction with annotations.

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

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

Two sentences, front-loaded with essential action and outcome. Every sentence adds value, including the credit usage note. 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?

Without an output schema, the description should clarify the return format but does not. 'Right page resolved' is vague. Parameter info is adequate, but overall completeness is moderate for a complex data retrieval tool.

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

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

Schema coverage is 83%, so description adds minimal extra meaning. The description implies domain/companyName are key but does not elaborate on formats or defaults beyond what 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?

The description uses a specific verb ('Pull') and resource ('brand's real running ads') across multiple platforms. It distinguishes from siblings like 'search_meta_ads' by offering a consolidated, deduped view.

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

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

No explicit guidance on when to use this tool versus searching individual ad libraries or other competitors tools. The description mentions credit cost but not decision criteria.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false), description adds 'Paid render' cost info. No contradictions. Additional transparency about being a render job, but could mention rate limits or job queuing.

Agents need to know what a tool does to the 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 concise: two sentences plus cost note. Key information front-loaded. No filler; each word 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?

Covers core purpose, required inputs, and cost. Lacks details on output format, duration, or limitations (e.g., max video length). Adequate for typical usage, but not exhaustive.

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

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

Schema coverage is 100%, so baseline 3. Description rephrases parameter roles (e.g., 'image supplies identity') but adds limited new semantic detail beyond schema descriptions. The 'orientation' parameter is explained in context.

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

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

Description clearly states verb 're-perform motion' and specifies resources (reference video, image). Distinct from siblings like 'generate_video' or 'dub_video' by focusing on motion transfer with identity swap.

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

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

Explains that reference clip drives motion and image supplies identity, providing clear context. However, no explicit exclusions or alternatives mentioned, though usage intent is well implied.

Agents often have multiple tools that could apply. Explicit usage 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 readOnlyHint=false and destructiveHint=false. The description adds that it is a 'paid render' and 'returns the served URL', providing cost and output format details beyond the annotations. No contradictions.

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

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

Two sentences with no redundant content. Every word adds value: purpose, example, cost, output. Excellent conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 tool with two parameters and no output schema, the description covers the core behavior, cost, and return format. It could mention potential limitations or prerequisites, but is complete enough for understanding.

Complex tools with many parameters or behaviors need more documentation. 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 parameters described. The description does not add extra meaning beyond the schema for either parameter; 'smart subject tracking' is a feature but not parameter-specific. Baseline 3 is appropriate.

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

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

The description clearly states the tool reframes video to a different aspect ratio with smart subject tracking, including a concrete example ('16:9 master → 9:16 vertical'). It distinguishes itself from sibling video tools (e.g., dub_video, stitch_video) by focusing specifically on reframing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 implicitly indicates usage for aspect ratio changes, and mentions it's a paid render which is a cost hint. However, it lacks explicit when-to-use or when-not-to-use guidance compared to alternatives, though the purpose is clear enough 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?

Discloses behavioral traits beyond annotations: explains that using brandId switches the active brand (like use_brand), and that the tool bills as one image generation. Annotations indicate non-read-only and non-destructive, and description confirms it creates a new image without modifying source.

Agents need to know what a tool does to the 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 adds value: first states purpose, second specifies imageUrl, third explains brandId and side effect, fourth limits scope to images, fifth mentions billing. 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?

Given the tool's simplicity (2 params, no output schema), the description is complete: covers all inputs, behavior, side effects, and alternatives. No gaps identified.

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

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

Adds significant meaning beyond schema: for imageUrl, it clarifies it's the static ad to remix; for brandId, it explains the side effect of switching active brand. Schema descriptions are basic, so tool description enriches them.

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

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

The description clearly states the tool's purpose: remix a static ad image into an on-brand version while preserving layout and composition. It distinguishes itself from sibling tools by explicitly noting 'IMAGES ONLY' and directing video ad use to render_ad.

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

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

Provides explicit guidance: use for static images only, alternative tool for video ads (render_ad), and explains how to use brandId to switch active brand. The description also clarifies billing implications ('Bills as one image generation').

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

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

Description discloses key behaviors beyond annotations: credit spending, render time (1-3 min), automatic stitched acts for plans >15s, no time-compression, text composited (not model-painted), and dryRun option. No contradiction with readOnlyHint=false or destructiveHint=false.

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

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

Description is detailed but front-loaded with recommendation and purpose. Some redundancy (e.g., mentions single pass/stitched both in description and schema), but overall efficient for the 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?

Given the complex tool with 11 params and nested objects, the description covers behavioral traits (stitching, credit cost, polling) but lacks explicit output/return format. However, output is handled via get_job polling, so completeness is adequate.

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

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

Schema coverage is 82%, and description adds meaning: creative must be full plan_ad output, model usage is deliberate, dryRun is free, resolution options imply credit cost. Adds context beyond schema, though nested creative object is briefly described.

Input schemas describe structure but not intent. Descriptions should explain 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 specifies the tool's function: rendering a plan_ad concept through the same quality pipeline as Hermoso web Studio. It distinguishes from sibling tools like make_template_ad by stating 'RECOMMENDED for finished video ADS' and detailing unique behaviors (e.g., stitched acts for longer plans, no model-painted text).

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

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

Explicit guidance: 'RECOMMENDED for finished video ADS' and 'Pass plan_ad’s full structured output as creative.' It contrasts with alternatives by noting when not to use (e.g., not for templates). Also provides context on polling (get_job) and credit spending.

Agents often have multiple tools that could apply. Explicit usage 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 provide readOnlyHint (true) and openWorldHint (true). The description adds behavioral context beyond annotations: it reveals cost (spends LLM tokens + ScrapeCreators credits) and return format (summary + found ads with served URLs). No contradictions.

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

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

The description is two sentences, front-loaded with the primary purpose, followed by key details (platforms, return, cost). No redundant or unnecessary 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 the tool's complexity (multi-platform, internal loop) and lack of output schema, the description is fairly complete: it specifies platforms, return content, and cost. Minor omissions like pagination or limits are acceptable for a research 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 has 2 parameters with 50% coverage (only query described). The description adds meaning for query via an example, but the brand parameter (anyOf string/object) is not explained. Schema coverage is moderate, so a baseline of 3 is appropriate; the description compensates partially but incompletely.

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

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

The description clearly states the tool performs natural-language ad research by looping over Meta/Google/LinkedIn ad libraries + organic TikTok, returning a summary and found ads. This distinguishes it from platform-specific sibling tools like search_meta_ads, search_google_ads, etc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 mentions it uses a Claude tool-use loop and spends LLM tokens + credits, implying resource-intensive use for cross-platform research. However, it does not explicitly state when to use this tool versus alternatives like individual search tools, leaving some inference to the agent.

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

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

Annotations indicate readOnlyHint=true, so the description correctly implies no side effects. It adds no additional behavioral details beyond what is stated, which is acceptable given the annotation coverage.

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

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

Two concise sentences that front-load the core purpose and use case. No extraneous information; every sentence adds value.

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

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

Given the tool's low complexity (3 params, no nested objects) and lack of output schema, the description covers the key aspects: input type, purpose, dimensions scored, and best use case. It is sufficiently complete for an agent to decide when and how to invoke it.

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

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

The schema covers 67% of parameters with descriptions, and the description adds context by mentioning the overall purpose and output breakdown. However, it does not explain the 'kind' parameter or how 'intent' is used, leaving some gaps.

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

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

The description states it predicts virality/performance for finished ads, listing specific dimensions and mentioning the single biggest fix. This clearly distinguishes it from siblings like planning or rendering 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 explicitly says 'Use BEFORE spending on distribution, or to rank variants,' providing clear context for when to use the tool. However, it does not elaborate on when not to use it or mention alternatives.

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

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

Adds critical context beyond annotations: returns raw provider JSON (large/messy), spends credits, rejects non-allowlisted paths, and param names vary. 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?

Slightly long but front-loaded with purpose and valuable details; each sentence earns its place. Minor room for tightening.

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

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

Covers purpose, usage, warnings, and platform list. No output schema but return value nature described. Good for complexity level.

Complex tools with many parameters or behaviors need more documentation. 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 description adds meaning: path must be exact endpoint, params vary per endpoint, gives examples (handle, query, subreddit).

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

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

The description clearly states it's a generic escape hatch for allowlisted endpoints, providing examples and listing supported platforms, distinguishing it from sibling search_* 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?

Explicitly states when to use (for endpoints not covered by search_* tools) and when not to (prefer dedicated tools), with warnings about raw JSON and credit usage.

Agents often have multiple tools that could apply. Explicit usage 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 read-only and open world. Description adds beyond: explains credit cost (1 vs 25), fetch variant (BASIC), and return structure. Could be 5 but lacks mention of any other behavioral traits like rate limits or pagination.

Agents need to know what a tool does to the 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 purpose and alternative, 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 simple read tool with no output schema, the description provides the return format and enough behavioral context (cost, variant) to select 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% and schema descriptions already explain limit and region defaults. The description adds 'by domain or advertiserId' clarifying the primary parameters but does not add new semantics beyond schema.

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

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

The description clearly states the tool pulls structured Google Ads Transparency for ONE advertiser by domain or advertiserId, and distinguishes from research_ads for open-ended research.

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

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

Explicitly says when to use (know the brand) and when to use sibling research_ads instead, plus mentions the cheap BASIC variant vs expensive detailed variant.

Agents often have multiple tools that could apply. Explicit usage 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 and openWorldHint. Description adds that results are organic, ranked by plays, and credits cost ~1. No contradictions.

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

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

Three sentences packed with essential info, no fluff. Purpose and scope 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?

No output schema, but description fully explains return format (compact JSON with specific fields), ranking, and credit usage. Complete for a search tool.

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

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

Schema coverage is 100% with descriptions for both 'query' and 'limit'. Description adds little beyond schema, just implying keyword search and mentioning the limit default (already in 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?

Clearly states it performs 'Organic Instagram REELS keyword search' and distinguishes from profile/hashtag pulls via scrapecreators_fetch. Cites specific endpoint and notes it's the only IG keyword surface.

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

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

Explicitly tells when to use this tool (keyword search for IG reels) and when to use the alternative (scrapecreators_fetch for profile/hashtag). Also mentions credit cost.

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

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

Annotations already mark it as read-only and open-world. Description adds value by detailing return structure, unique impression counts, and credit cost. Does not discuss pagination or rate limits, but overall good 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?

Three sentences, each serving a distinct purpose: usage guidance, output description, and cost/uniqueness note. Front-loaded and 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?

Describes return format despite no output schema, and clarifies uniqueness of impression counts. Lacks mention of error handling or empty results, but overall sufficiently complete for a search tool with 5 parameters.

Complex tools with many parameters or behaviors need more documentation. 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 80%. Description adds explicit range and default for limit (1–25, default 8), and explains countries parameter with examples. However, core parameters (company, keyword, companyId) lack additional detail beyond 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?

Clearly states it's a structured search of the LinkedIn Ad Library by company name, keyword, or companyId. Distinguishes from sibling research_ads, which is for open-ended research. Verb+resource+scope are explicit.

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

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

Provides explicit guidance: 'use for a targeted B2B pull; use research_ads for open-ended research.' Also mentions credit cost and return format, giving clear context for when to invoke.

Agents often have multiple tools that could apply. Explicit usage 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 read-only nature (consistent with readOnlyHint=true), open-world hint, credit cost, and return format. No contradictions.

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

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

Two sentences plus return hint; front-loaded purpose. No fluff.

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

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

Given 7 parameters, no required fields, no output schema, and good annotations, description provides sufficient context: purpose, usage constraints, return fields, and credit impact.

Complex tools with many parameters or behaviors need more documentation. 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 covers 86% of parameters with descriptions. Description adds value by clarifying parameter use cases (e.g., query vs companyName/pageId), slightly exceeding 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?

Clearly states it's a structured pull from Meta Ad Library, returns compact JSON with specific fields. Distinguishes from sibling tool research_ads by specifying use case.

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

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

Explicitly says 'use when you know exactly WHAT to fetch' and directs to research_ads for open-ended research. Also notes credit consumption.

Agents often have multiple tools that could apply. Explicit usage 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 context beyond annotations by detailing the return format (compact JSON with desc, subreddit, etc.) and credit cost. Annotations already indicate a safe read operation and open-world nature.

Agents need to know what a tool does to the 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 information-dense sentences: first describes the action and endpoint, second explains the value and output. No fluff, front-loaded with key information.

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

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

For a simple tool with two parameters and no output schema, the description sufficiently explains the output structure and use case. Minor lack of pagination or sorting details, but not critical.

Complex tools with many parameters or behaviors need more documentation. 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 description clarifies the practical limit range (1-25) and default (8) beyond the schema's generic integer bounds, and it explains the query parameter's purpose. Schema coverage is 100% so the description adds meaningful nuance.

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

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

The description clearly states it performs a Reddit keyword search, specifies the endpoint and ranking, and differentiates it from sibling tools that search other platforms like Google Ads or Instagram.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 explains the tool's value for mining customer language into ad copy, implying when to use it. However, it does not explicitly state when not to use it or contrast with other search tools beyond sibling names.

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

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

Annotations provide readOnlyHint and openWorldHint; the description adds credit cost ('Spends ScrapeCreators credits (~1)') and return format details, going beyond annotations without 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?

Two sentences with no waste: first sentence defines purpose and endpoint, second covers return format and cost. Front-loaded and efficient.

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

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

Given no output schema, the description explains return fields and credit cost. Adequately covers a simple search tool with two parameters; could mention pagination or rate limits but not critical.

Complex tools with many parameters or behaviors need more documentation. 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% for both parameters (query and limit), so baseline is 3. The description does not add additional parameter semantics beyond what the schema already provides.

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

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

The description states 'Organic Threads keyword search' and specifies it returns compact JSON for trend + voice research, clearly identifying the tool's purpose. It distinguishes from sibling search tools (e.g., search_instagram, search_tiktok) by naming Threads explicitly.

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

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

The description implies usage for Threads trend and voice research but does not provide explicit when-to-use or when-not-to-use guidance. No alternatives are named, though context hints at platform-specific use.

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

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

Discloses beyond annotations that the tool is read-only and open-world. Adds that results are compact JSON with specific fields ranked by plays, and that it's organic (no ad library). No contradictions with annotations.

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

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

Two concise sentences, front-loaded with purpose and key details. Every sentence adds value: purpose, exclusions, return format, alternative tool, and cost. 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 simple tool with 2 parameters and no output schema, the description fully covers purpose, return format, cost, and usage context. No gaps in understanding how to invoke or interpret results.

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

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

Schema coverage is 100% with descriptions for both parameters. The tool description does not add new parameter information beyond what is in 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?

Clearly states it's an organic TikTok keyword search, specifies it returns top-performing videos for hooks/trends/remixable creative, and distinguishes from a non-existent ad library. The verb 'search' and resource 'TikTok' are specific, and it isolates from siblings like research_ads.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 provides when to use: 'Use research_ads for open-ended research.' Also notes credit consumption, guiding the agent on cost implications. No other siblings are relevant for similar keyword search.

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

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

Beyond annotations (readOnlyHint, openWorldHint), the description adds that it uses credits (~1) and specifies the return format and fields, providing useful 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?

Two sentences, no wasted words. The purpose is front-loaded, and every sentence adds value.

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

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

For a simple read-only tool with two parameters, the description covers the return format, credit cost, and usage context. Minor gap: no mention of pagination or error handling, but adequate given low complexity.

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

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

The schema already provides descriptions for both parameters with 100% coverage. The description adds the credit cost but does not further explain parameter 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?

The description clearly states the tool performs 'Organic YouTube keyword search' and specifies it returns videos for mining hooks/angles, distinguishing it from other search tools for different platforms among siblings.

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

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

The description implies usage for content research ('videos to mine for hooks/angles/long-form structure'), but does not explicitly state when not to use or compare to alternatives like search_tiktok or search_reddit.

Agents often have multiple tools that could apply. Explicit usage 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 server-side operation, card requirement, and error messaging beyond annotations. No contradiction with readOnlyHint=false or destructiveHint=false.

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

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

Informative without fluff, but a single dense paragraph—could be broken into bullet points or clearer sections. Still efficient.

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

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

Covers prerequisites, behavior, admin scope, effect on members, and error response. No output schema, but description adequately explains outcomes.

Complex tools with many parameters or behaviors need more documentation. 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 has 100% coverage; description adds value by linking reloadCredits to buy_credits pack sizes and specifying thresholdCredits triggers. Minor gap: no example values or validation 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 clearly states the tool turns automatic credit reloads on or off, specifies it's admin-only, and distinguishes it from siblings like buy_credits by mentioning credit pack sizes.

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

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

Provides explicit prerequisites (saved card), admin-only restriction, member behavior ('ask an admin'), and error handling direction, enabling correct selection and invocation.

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

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

Beyond annotations (readOnlyHint=false, openWorldHint=true), the description details the download, product+safety check, rejection criteria, persistence to a durable URL, billing one vision check, and brand switching. This fully discloses the tool's behavior and side effects.

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

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

The description is detailed but well-structured, with key terms bolded and logical flow. Every sentence provides necessary information without redundancy. It is appropriately concise for the complexity of the tool.

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

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

Given no output schema, the description fully explains return values (durable URL on pass, rejection summary) and side effects (billing, brand switching). It references sibling tools (list_product_photos, generate_image, render_ad, use_brand) and clarifies prerequisites, making it complete for the tool's complexity.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds context for imageUrl (acceptable sources), brandId (locking for a brand and switching active brand), and source_note (purpose of note). This adds clarity beyond the 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 clearly states the tool's purpose: 'Lock an image as the ad's real PRODUCT photo so every render grounds on the true packaging.' It uses a specific verb ('Lock') and resource ('product photo'), distinguishing it from sibling tools like use_brand or generate_image.

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

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

The description tells when to use the tool (to lock a product photo for an ad) and what inputs are acceptable (imageUrl from research results, workspace URLs, etc.). It also explains the outcome (rejection vs. durable URL) and how to use the result with generate_image/render_ad. However, it could more explicitly contrast with alternatives like list_product_photos.

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

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

Description adds behavioral context beyond annotations: 'Blocks until done. Spends credits.' Annotations already indicate readOnlyHint false and openWorldHint true, so this aligns and adds value. Could mention credit cost details but sufficient.

Agents need to know what a tool does to the 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 front-loaded purpose, then conditions and alternatives. Every part earns its place; 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?

Tool has 7 parameters and no output schema. Description covers purpose and usage well but lacks parameter details and return value. Adequate for core function but incomplete for complex usage.

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

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

Schema coverage is only 14% (only scenes has description). Description reinforces scenes must have ≥2 items but provides no details on other 6 parameters (model, voice, resolution, etc.). Minimal added meaning beyond schema's minItems.

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

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

Description clearly states the tool renders a multi-scene stitched video, with explicit condition of ≥2 scenes and >15s spots. It distinguishes from siblings generate_video/render_ad for shorter ads.

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

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

Explicitly says when to use (spots >15s) and when not to (≤15s use generate_video/render_ad), naming alternative tools. Clear guidance prevents 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?

Describes behavior beyond annotations: returns Stripe URL or instructions, agent never spends money, members get admin message. However, initial 'Change' contradicts readOnlyHint=true annotation, causing some confusion.

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

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

Well-structured with purpose first, then stepwise logic. Slightly lengthy but each sentence adds value. Could be more concise but still clear.

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

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

Comprehensive coverage of behavior for all user types and billing states, including admin requirements and payment flow. No output schema needed given the detailed description.

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

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

Adds meaning to both parameters: plan ID example ('pro'), period as cadence with yearly discount. Explains that omitting plan lists options, which is not in schema. Schema coverage is 100% but description enhances usability.

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

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

Clearly states it changes subscription plan, lists plans when called without argument, and covers various user scenarios. Distinguishes from siblings like billing_status and buy_credits by focusing on plan changes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 specifies admin-only, two-step process (list then set plan), and scenarios for new subscribers, existing paid, downgrades, and members. Provides clear usage context but lacks explicit comparison to sibling tools.

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

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

Annotations indicate non-read-only (mutation) and non-destructive. The description adds key behavioral context: 'Paid render' (cost implication) and 'returns the served URL' (output type). This goes beyond annotations, though rate limits or exact pricing are not disclosed.

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

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

A single sentence containing all essential information: action, resource, outcome, side effect, and output. No wasted words. Front-loaded with the primary action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 simple input schema (one parameter), no output schema, and annotations, the description fully covers what the tool does, its side effects, and its output. No missing information for basic usage.

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

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

Schema coverage is 100% with a clear description for the single 'video' parameter. The tool description does not add extra detail (e.g., accepted formats, max size, quality options) beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the specific action (upscale), resource (video), target resolution (2x), context (final delivery), and result (served URL). It distinguishes from sibling tools like generate_video or reframe_video by focusing on resolution enhancement.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 for final delivery when a higher resolution is needed, but does not explicitly state when to use this tool versus alternatives (e.g., reframe_video for cropping, generate_video for new creation). No when-not-to-use or alternative guidance is provided.

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

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

The description discloses that the effect persists for the API key until changed, which is beyond the readOnlyHint=false and destructiveHint=false annotations. It clearly indicates a state change without destruction. No contradictions 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 two sentences with no wasted words. The first sentence front-loads the purpose, the second adds essential detail. Every sentence contributes meaning.

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

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

Given the tool's simplicity (single parameter, no output schema, annotations present), the description covers the purpose, usage context, and persistence behavior completely. No additional information is needed for correct invocation.

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

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

The single parameter 'brand' is fully described in the schema (100% coverage). The tool description adds value by explaining the source of valid values ('from list_brands') and examples (default / p_xxx), which aids correct invocation beyond the schema alone.

Input schemas describe structure but not intent. Descriptions should explain 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 action ('pin which brand this connection generates for'), the resource (brand for multi-brand accounts), and how to specify it (id or exact name from list_brands). It distinguishes itself from sibling tools like list_brands and get_brand by specifying it affects the connection's generation.

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

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

The description explicitly says when to use it (multi-brand accounts) and what input to provide (brand id or exact name from list_brands). It implies prior use of list_brands, but does not explicitly state when not to use or alternative tools. The context is clear enough for an agent.

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