Heista

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

Describes the full pipeline: download, vision tagger, storage in bucket, row insertion. Notes that failure leads to type=general save. Adds context beyond annotations (readOnlyHint=false, destructiveHint=false). 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?

Single paragraph with no redundant sentences. Information is front-loaded, and every sentence adds 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?

No output schema, but description explains what happens to the asset (saved, row inserted, type if fail). References retag_brand_asset for retry. Adequate for a creation 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?

Schema coverage is 100% with descriptions for both parameters. Description reinforces that image_url is a public HTTPS URL and details the pipeline, 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?

Description starts with 'Upload an image to a brand by URL' clearly stating the action and resource. It distinguishes from siblings like retag_brand_asset (retry tagging) and delete_brand_asset (deletion).

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

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

Explicitly states 'Paid (vision tag credit)' indicating cost. Mentions fallback when vision tagging fails and suggests retag_brand_asset for retry, guiding when to use this vs. alternative.

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

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

Annotations already declare readOnly/ idempotent. Description adds 'Free, read-only, idempotent' and details on return fields, 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?

Well-structured with front-loaded purpose, but slightly lengthy; every sentence adds value, though could be slightly more concise.

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

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

With no output schema, description explains exactly what each formula returns (source ad count, etc.) and how to use with generate_adscript, ensuring complete 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 high (100%), but description adds context through examples for each filter and explains limit default, 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?

The description clearly states the tool browses proven ad formula blueprints, a specific verb+resource. It distinguishes from siblings like decode_ad (specific ad) and generate_adscript (synthesis).

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 (pattern discovery in categories) and when not to (specific ad → decode_ad). Provides prioritization criteria among results.

Agents often have multiple tools that could apply. Explicit usage 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 the tool is one-shot, non-interactive, and metered (3-15 credits). Explains the output shape switching, idempotency_key feature, and that for uncovered mediums the alternate tool should be used. 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 lengthy but well-structured and front-loaded with the core purpose. Each section (output shapes, usage guidelines, inputs) is organized logically. While it could be slightly more concise, the complexity justifies the length.

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

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

Covers all aspects: purpose, when to use, when not to use, input details, output shape descriptions, metering, and retry behavior. Despite lacking an output schema, the description clearly explains what is returned. Complete for a complex 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%, but the description adds significant value by detailing the output shape for each medium, providing examples for brief, and explaining the purpose of brand_id, lens_hint, and idempotency_key. This goes 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 is a one-shot creative direction engine that generates N finished creative outputs from a brief. It distinguishes itself from the sibling chat_with_creative_worlds tool by specifying when to use each (one-shot vs refinement). The purpose is specific and unambiguous.

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

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

Contains explicit 'USE WHEN' and 'DO NOT USE' sections, listing concrete scenarios. It directs users to chat_with_creative_worlds for back-and-forth refinement or mediums not covered by the enum, providing clear 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 metering (2-10 credits per turn, charged on actual usage), session persistence behavior (session_id lifecycle), and creative director personality (anti-cliché, specificity test, pushback on vague briefs). Annotations only indicate mutability; description adds rich behavioral context 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?

Long but well-organized with clear sections (WHAT YOU CAN ASK FOR, SESSION, USE WHEN, WON'T DO, Metered). Front-loaded with purpose. Each sentence adds value, though length could be trimmed slightly without losing substance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 for a complex multi-turn tool with no output schema. Covers request types, session management, cost, limitations, and edge cases (brand_id turn 1 only). Provides everything an agent needs 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?

All 3 parameters have schema descriptions (100% coverage). Description adds significant value: message examples for first vs subsequent turns, brand_id only honoured on turn 1, session_id for continuation vs new sessions. Exceeds schema documentation.

Input schemas describe structure but not intent. Descriptions should explain 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 'Multi-turn conversation with Heista's creative direction engine'. Distinguishes from sibling tool call_creative_worlds by explicitly noting when to use this tool (needs >1 round or output shape outside enum). Verb 'chat' and resource 'creative direction engine' 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 states 'USE WHEN' conditions (back-and-forth, output shape outside medium enum) and 'WON'T DO' (OKRs, internal docs, general assistant). Directs to prefer call_creative_worlds for one-shot requests. Also provides examples of acceptable requests.

Agents often have multiple tools that could apply. Explicit usage 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, idempotentHint=true, destructiveHint=false. Description adds that it is free, returns balance in cents, lifetime spend in cents, month-to-date call counts per tool, per-tool unit pricing, and a top-up link. No contradictions. The extra details about what the return includes add value 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?

Description is well-organized: starts with a clear summary of what the tool does, then enumerates return fields and usage guidelines. While a bit lengthy, every sentence serves a distinct purpose. The first sentence effectively front-loads the core functionality.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 fully describes all return values (balance in cents, lifetime spend, month-to-date call counts per tool, per-tool pricing, top-up link). It also covers when to use, when not to, and idempotency/read-only nature. No gaps for a zero-parameter 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 in the input schema. The description states 'Takes no inputs', which is sufficient. With 100% schema description coverage (empty schema fully described), baseline 3 is exceeded because the description confirms and adds context about the no-parameter 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 it checks the user's Heista API credit balance, month-to-date usage, lifetime spend, and pricing. The verb 'check' and resource 'balance' are specific, and it distinguishes from siblings (no sibling tool deals with billing or credits).

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

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

Explicitly lists when to use (user asks about credits, balance, usage, pricing, etc.) and when not to use (adding credits, calling on every turn). Also provides cross-tool guidance about dollar vs credit reporting, making it clear this is the exclusive surface for monetary values.

Agents often have multiple tools that could apply. Explicit usage 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 critical behavioral context beyond annotations: it's asynchronous (returns job_id), costs 100 credits, reads text only (PDFs must be converted), and output shape matches create_powersource_url. 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 relatively long but well-structured and front-loaded with the core purpose. Every sentence adds value, though some repetition (e.g., 'text only') could be condensed. Still, it earns its length.

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

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

For a 6-parameter tool with no output schema, the description covers input methods, async behavior, cost, output shape, and usage context. Slightly lacking on what happens if no document sources are provided (all params optional). Overall, fairly 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 baseline is 3. The description enriches parameters significantly, especially documents_inline with detailed processing instructions (extract text, base64 text file). It also clarifies brand_id auto-resolution and idempotency_key behavior, going 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's purpose: 'Build a complete creative intelligence profile from internal brand documents' with specific document types. It distinguishes from siblings by explicitly listing when to use this vs create_powersource_url and create_powersource_full.

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

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

The description provides explicit when-to-use guidance ('Use this when the user says...') and when-not-to-use ('Do NOT use for URL-only scans...'). It directly names alternatives (create_powersource_url and create_powersource_full) with clear differences.

Agents often have multiple tools that could apply. Explicit usage 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 and openWorldHint=true. Description adds: costs 200 credits, returns job_id (async), poll with get_powersource, same response shape as create_powersource_url, and cross-checks public vs internal. 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?

Well-structured, front-loaded with purpose, each sentence adds value, no redundancy. Usage guidelines and exclusions are clearly separated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 complexity (6 params, no output schema), description covers all essential aspects: required inputs, optional parameters, async behavior, polling, cost, and comparisons with siblings.

Complex tools with many parameters or behaviors need more documentation. 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%; descriptions already detailed. Description adds context: requires at least one document, explains document sources (file_ids, document_urls, documents_inline) and the idempotency_key purpose.

Input schemas describe structure but not intent. Descriptions should explain 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 builds a creative intelligence profile by combining URL and documents, distinguishes from siblings create_powersource_url and create_powersource_docs, and explains the unique cross-checking value.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 (both inputs available) and when not (URL-only or docs-only), names alternative tools, and mentions cost and default recommendation.

Agents often have multiple tools that could apply. Explicit usage 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 cost (100 credits), caching behavior (re-scan free), polling instructions (every 3-5s, 60-90s total), and final payload structure (14 sections). This adds significant context beyond annotations, which only indicate readOnlyHint=false and 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?

The description is well-structured with clear sections but slightly verbose (4 paragraphs). It front-loads the main purpose and use cases. Minor redundancy could be trimmed, but overall effective.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 (async, polling, webhook, cost, caching), the description covers all essential aspects including return behavior, polling frequency, cost, and output structure. No output schema exists, so the description must explain return values, and it does.

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

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

Schema description coverage is 100%, so the baseline is 3. The description briefly mentions optional parameters (idempotency_key, force_refresh, webhook_url) but does not add significant new semantics beyond the schema's parameter descriptions.

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

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

The description clearly states it 'Build a complete creative intelligence profile of a brand from a single website URL', specifies the verb and resource, and distinguishes from siblings like create_powersource_docs and create_powersource_full.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 when-to-use examples ('analyse my brand', 'load my brand', etc.) and when-not-to-use (internal docs/PDFs, video ads) with alternative tool names. Also mentions using it before generate_adscript.

Agents often have multiple tools that could apply. Explicit usage 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 async behavior (returns job_id, poll every 15s, typical 45-60s), credit costs (15 for ≤60s, 20 for 61-120s), supported platforms, and input type restrictions. Annotations show readOnlyHint=false (consistent with mutation) and idempotentHint=false (description explains key provides idempotency). 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?

Description is well-structured with clear sections (what it does, when to use, what not to use). Slightly verbose but every sentence adds information. Front-loaded with 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?

No output schema, but description fully explains return format (job_id), polling procedure, typical timing, costs, and platform support. Covers all essential behavioral and usage context for an async operation 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 covers both parameters with descriptions, but description adds value: explains idempotency_key prevents re-charging, and url parameter gets platform-specific context (Facebook, TikTok, etc.) and cost implications per video length.

Input schemas describe structure but not intent. Descriptions should explain 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 opens with specific verb+resource ('Decode a specific video ad URL into its full structural formula') and lists detailed output components (beat-by-beat, hook classification, etc.). Clearly distinguishes from sibling tools like decoder_intelligence and adformula_intelligence by stating what not to use it for.

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

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

Explicitly states when to use: when user pastes ad URL, names competitor ad, asks 'decode this', or wants sentence-level fidelity before script generation. Also gives explicit negative guidance: not for browsing or image ads, and directs to free alternatives for discovery.

Agents often have multiple tools that could apply. Explicit usage 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 idempotentHint=true. Description adds 'Free, read-only, idempotent — no credits consumed' and explains return fields and linkage to get_decode, providing context 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?

Well-structured and front-loaded with purpose and filters. Slightly long but each sentence adds value; could tighten slightly without loss.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 details return contents (beat timeline, classification, etc.) and links to generate_adscript. Covers usage boundaries and alternatives, making it complete for a browse 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% and each parameter has a description. The description adds examples and clarifies behavior (e.g., 'Omit for all'), adding 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 states it browses individual decoded ads from Heista's corpus of winning Meta/TikTok creative. It lists specific filters and distinguishes from siblings by mentioning alternatives for other tasks.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 (e.g., 'when the user wants a specific ad as a script template') and when not to use, with alternatives like decode_ad, adformula_intelligence, and generate_adscript.

Agents often have multiple tools that could apply. Explicit usage 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 (destructiveHint=true, idempotentHint=true), the description explains exactly what gets deleted: the brand_assets row and, if uploaded, the storage object. This adds valuable 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 substantive sentences plus a directive, front-loaded with the core purpose. 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 single-parameter destructive tool, the description covers purpose, behavioral effects, and usage steps. Minor gap: no mention of return value or behavior on non-existent asset, but idempotentHint suggests safe re-calls.

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

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

Schema coverage is 100% with a description referencing list_brand_assets. The description reinforces this guidance but adds no new 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 states the action (delete), resource (brand asset by asset_id), and distinguishes from siblings like list_brand_assets and add_brand_asset. It specifies the scope: removes row and optionally storage object.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 when-to-use (destructive deletion) and prerequisite (use list_brand_assets first to find asset_id). Directs confirming with user before calling, which is strong 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 declare destructiveHint=true and idempotentHint=true. The description adds critical details: OAuth vs API-key permissions, cleanup of storage objects for private VISUALS/MOTION, and need for user confirmation. 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?

Four sentences, no fluff. Front-loaded with purpose and critical warning. Every sentence serves a purpose: purpose, safety, auth, side effect.

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

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

For a single-parameter destructive tool with no output schema, the description covers purpose, constraints, auth behaviors, and side effects completely. Nothing essential is missing.

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

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

Schema has one parameter with full description (100% coverage). The description only adds 'Get from list_saved_assets' context, which is minimal but not needed beyond schema. Baseline 3 is appropriate.

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

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

The description begins with 'Delete one saved asset by id', which is a clear verb+resource statement. This distinguishes it from sibling tools like delete_brand_asset and save_asset.

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

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

It explicitly warns 'Destructive — confirm with the user before calling' and explains authorization differences between OAuth and API-key callers. No explicit when-not-to-use, but sufficient for safe 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?

The description outlines the return structure in detail (BRIEF restatement, NOT IN SCOPE, findings with labels, citations, Sources block) and mentions multi-source extraction with citation discipline. Annotations are non-contradictory, though the description does not disclose potential side effects beyond what annotations imply.

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

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

The description is concise, using a single paragraph with clear separation of use cases and return structure. Every sentence adds value; no redundant 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 moderate complexity (5 parameters, no output schema), the description sufficiently covers purpose, usage boundaries, and output format. It lacks some details like handling of ambiguous inputs but is adequate for an AI 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% with detailed parameter descriptions. The tool description adds minimal value beyond the schema for parameter understanding, but it does provide context on what the tool returns, which indirectly relates to parameters. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'source-grounded synthesis on a topic landscape.' It provides specific example queries and explicitly distinguishes from sibling tools by listing what NOT to use it for, including the exact sibling tool names.

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

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

It explicitly lists use cases ('Use for:') and non-use cases ('NOT for:') with mappings to alternative sibling tools. This gives the agent clear when-to-use and when-to-avoid 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?

The description adds significant behavioral context beyond annotations: it explains async execution (returns job_id, durable Vercel Workflow, no 300s timeout), idempotency (same brief+org reuses same job_id), and the return format structure (BRIEF + NOT IN SCOPE + findings with labels + citations + Sources). This fully informs the agent of behavior.

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

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

The description is well-structured with clear sections: purpose, use cases, async details, idempotency. It is somewhat long but every sentence adds value, and critical information is front-loaded. Minor verbosity in examples 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 complexity (5 parameters, async pattern, no output schema), the description covers purpose, usage, behavioral traits, return format, idempotency, and retrieval instructions. It fully equips the agent to understand and invoke the tool correctly, including how to handle async 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 in the schema itself. The tool description does not add new meaning to the parameters beyond the schema; it only mentions them in passing. Therefore, the description provides no extra value for parameter understanding beyond what the schema already offers, yielding a baseline score of 3.

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

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

The description clearly states 'Dispatch to the DESK RESEARCHER — source-grounded synthesis on a topic landscape' and provides specific example queries. It explicitly distinguishes from four sibling tools by listing what it is NOT for, making the purpose unambiguous and differentiating it from alternatives.

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

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

The description explicitly says 'Use for:' and 'NOT for:' with specific alternative tool names (dispatch_trend_researcher, dispatch_market_analyst, etc.). It also explains when to use the async version (when expected >90s) and how to retrieve results, providing complete usage 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 provide readOnlyHint=false, openWorldHint=true, idempotentHint=false. The description adds context: it uses async dispatch, polls, judges quality, and returns a structured synthesis with fields like synthesis, head_session_id, status, etc. No contradiction, but could mention persistence of results or cleanup.

Agents need to know what a tool does to the 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 moderately long but well-structured with logical sections (what, how, use for, not for, time, cost, returns). Every sentence adds information; no fluff. Could be slightly tighter 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?

Given the complexity of an orchestration tool, the description covers purpose, usage, behavioral traits, parameters, cost, and return structure. It lacks output schema but compensates by listing return fields. It is sufficiently complete for agent decision-making.

Complex tools with many parameters or behaviors need more documentation. 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% (baseline 3). The description adds value beyond the schema: for 'brief' it explains self-containment and advises on content; for 'priority' it clarifies that 'deep' uses better models; for 'max_wait_seconds' it gives default and typical completion times. This 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: 'Run a full research workflow via the Head of Research agent.' It specifies that it decomposes briefs, dispatches specialists, and returns a structured synthesis. This distinguishes it clearly from sibling tools like individual dispatch_* researchers.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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: 'any source-grounded research request' with examples, and when not to use: 'non-research requests (writing, coding, casual chat)'. Provides typical wall time (2-5 min) and cost range ($0.20-1.50), giving clear context.

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

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

Annotations provide minimal behavioral hints (readOnlyHint=false, openWorldHint=true). Description adds detail: multi-axis extraction, sourcing, and returns (8-axis extraction + MOAT + GAP + Sources). No contradiction; transparency is good but could mention 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 concise (approx. 100 words), front-loaded with verb phrase, and structured with explicit use cases and exclusions. Every sentence adds value with no redundancy.

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

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

Given 5 parameters (4 required) and no output schema, the description adequately explains purpose, output format, and exclusions. It could detail the return structure more, but already covers the 8 axes and thesis types.

Complex tools with many parameters or behaviors need more documentation. 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 parameters are already documented. Description does not add new parameter-level meaning beyond the schema, meeting baseline expectation.

Input schemas describe structure but not intent. Descriptions should explain 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 'entity-deep teardown of a named brand or vendor' and provides specific use cases. It distinguishes from siblings by explicitly stating what it is NOT for and naming alternatives (dispatch_desk_researcher, dispatch_trend_researcher).

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 usage guidance: 'Use for: ...' and 'NOT for: ...' with alternative tool names. Also notes vertical and geography agnostic, 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?

Goes beyond annotations by detailing async behavior: returns job_id immediately, runs on Vercel Workflow, no 300s timeout, and idempotent job reuse. No contradiction with readOnlyHint=false or idempotentHint=true.

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

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

Very concise with clear bullet-like structure. Every sentence adds value: purpose, use cases, exclusions, async mechanics, idempotency. 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?

Covers all necessary context: what tool does, when to use sync vs async, how to poll, idempotency, and alternatives. No output schema needed since return is just a job_id.

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

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

Schema coverage is 100% with good descriptions; description adds context but doesn't repeat param details. It gives high-level purpose for the tool that frames parameter usage. Baseline 3, slight bonus for framing.

Input schemas describe structure but not intent. Descriptions should explain 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 explicitly states it does 'entity-deep teardown of a named brand or vendor' and gives clear examples of use. It distinguishes from sibling tools like dispatch_desk_researcher and dispatch_trend_researcher with explicit NOT FOR clauses.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 when-to-use (brand/vendor teardown) and when-not-to-use (topic landscapes, category trajectories) with named alternatives. Also explains async polling pattern with get_dispatch_result and mentions idempotency for retry safety.

Agents often have multiple tools that could apply. Explicit usage 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: describes the return structure in detail (evidence count, triangulation, verbatim quotes, etc.) and mentions the 'Reddit/X/Substack named-operator voice retrieval gap' indicating external data access. 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?

Well-structured with bullet points, front-loaded purpose, and efficient sentences. Every sentence adds value without 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?

With no output schema, the description compensates by detailing the return format extensively. Covers inputs via schema, explains its role among siblings, and handles complexity well.

Complex tools with many parameters or behaviors need more documentation. 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 each field. The description adds high-level context but does not significantly enhance understanding of individual parameters beyond the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose as thematic synthesis from unstructured text, with specific use cases. It explicitly distinguishes from sibling tools like dispatch_quantitative_researcher and dispatch_social_listening_researcher by stating what it is not for.

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

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

Provides clear when-to-use examples ('Use for: ...') and when-not-to-use with direct alternatives ('NOT for: ... use dispatch_quantitative_researcher / dispatch_social_listening_researcher'). This leaves no ambiguity for 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=false (mutation), openWorldHint=true (external effects), idempotentHint=true. The description adds: async execution with immediate { job_id } return, durable Vercel Workflow (no 300s timeout), polling method, and idempotent retry logic. This provides significant behavioral context beyond annotations, though it could mention rate limits or authentication.

Agents need to know what a tool does to the 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 with clear sections: purpose, use cases, exclusions, async behavior, idempotency. Every sentence adds value, but the length is moderate (8 sentences). It could be slightly more concise without losing clarity, but the structure aids readability.

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

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

Despite no output schema, the description details return fields (Corpus, Sampling, Coding methodology, Themes table, Theme synthesis, Outlier voices, Saturation assessment, Sources). It covers async workflow, polling, and idempotency. This is highly complete for a complex tool with 5 parameters, leaving few gaps 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% with descriptive field names and minLength/maxLength hints. The description adds high-level context about parameter purpose (e.g., 'objective: one sentence stating what done looks like') but does not detail individual parameter behaviors or constraints. Given schema already covers meaning, a baseline of 3 is appropriate; description adds value via usage framing.

Input schemas describe structure but not intent. Descriptions should explain 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 specifies a concrete action ('Dispatch to the QUALITATIVE RESEARCHER — thematic synthesis from unstructured text') and provides clear use cases ('what are the 2-3 recurring themes...'). It distinguishes this tool from siblings ('NOT for quantitative effect sizes', 'NOT for multi-platform discourse mapping'), clarifying its unique role.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 (thematic analysis of unstructured text) and when not (quantitative effect sizes, social listening). Provides async-specific guidance: use when specialist takes >90s, call get_dispatch_result to poll. Discusses idempotency and retry behavior. This gives the agent clear 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, openWorldHint true, idempotentHint false), the description adds valuable behavioral context: it often returns 'insufficient-evidence' when data is thin, and negative findings are deliverable. It also describes the return structure (4-axis summary, numerical findings table, methodology gaps, sources). 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 a single, well-structured paragraph. It front-loads the purpose, then covers usage, behavioral notes, return format, and exclusions. Every sentence adds value with no redundancy.

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

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

Given the tool has 5 parameters, no output schema, and multiple siblings, the description is fully complete. It addresses purpose, usage boundaries, behavioral traits, output shape, and exclusion criteria. No gaps remain.

Complex tools with many parameters or behaviors need more documentation. 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 detailed descriptions for each parameter. The description does not add parameter-specific detail beyond the schema, but it provides high-level context for the objective and boundaries. Baseline 3 is appropriate as the schema carries most of the parameter burden.

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

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

The description clearly states it dispatches to a quantitative researcher for numerical analysis, using a specific verb ('Dispatch') and resource. It distinguishes from siblings by explicitly excluding topic landscapes and community language patterns, naming dispatch_desk_researcher and dispatch_qualitative_researcher as alternatives.

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

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

Provides explicit guidance on when to use: 'briefs that turn on numbers done rigorously' with examples. Also explicitly states when NOT to use, referencing sibling tools for those cases.

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

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

Discloses key behaviors: async dispatch returns job_id, runs durably via Vercel Workflow (no 300s timeout), idempotent (same brief+org reuses job_id), may return insufficient-evidence. Annotations support this (openWorldHint, idempotentHint) and 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?

Well-structured with clear sections: use cases, exclusions, async details. Information-dense but every sentence adds value. Slightly verbose but appropriate for 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?

Covers all critical aspects: purpose, usage guidelines, async mechanics, polling instructions, idempotency, return structure. No output schema but description adequately explains expected return ('{ job_id }' and polling).

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

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

Input schema covers 100% of parameters with clear descriptions. Description adds overall context but does not enhance individual parameter meanings beyond schema. Baseline 3 is appropriate.

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

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

Description clearly states it dispatches to a quantitative researcher for numerical analysis with methodology rigor. Provides specific use case examples ('effect size', 'data says', 'quantify impact') and explicitly distinguishes from sibling tools like dispatch_desk_researcher and dispatch_qualitative_researcher.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 ('briefs that turn on numbers') and when not ('topic landscapes', 'community language patterns'), naming alternatives. Also clarifies when to use async vs sync version based on expected duration (>90s).

Agents often have multiple tools that could apply. Explicit usage 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 value beyond annotations by detailing primary data sources (T3 community sources), sampling method (≥3 platforms), and output components. While annotations indicate openWorldHint=true (potential side effects), the description does not fully elaborate on non-deterministic behaviors, but overall provides substantial behavioral context.

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

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

The description is concise, well-structured with clear sections, and front-loads the core purpose. Every sentence serves a purpose with no redundancy.

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

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

Given no output schema, the description compensates by listing the return structure (Signal map, evidence trail, classification, confidence, sources). It also specifies sampling and primary data. While it could mention edge cases or error handling, it is sufficiently complete for a dispatch tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add significant parameter-specific information beyond what is in the schema, but it does not need to since the schema is already descriptive.

Input schemas describe structure but not intent. Descriptions should explain 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 dispatches to the SOCIAL LISTENING RESEARCHER for multi-platform community-signal interpretation. It lists specific use cases like tracking practitioner discourse and emerging jargon, and distinguishes from sibling tools by mentioning alternatives for single-source work and numerical sentiment analysis.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 tool includes explicit 'Use for:' and 'NOT for:' sections, providing clear when-to-use and when-not-to-use guidance, and names sibling tools (dispatch_qualitative_researcher, dispatch_quantitative_researcher) as 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 mutability and idempotency; the description adds detail on the async workflow, immediate job ID return, durable Vercel execution, and idempotent job reuse. 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 front-loaded with the main purpose, followed by use cases, exclusions, async specifics, and idempotency. Every sentence adds value; no redundancy. It is appropriately sized for the tool's complexity.

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

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

Given the async nature, sibling tools, and parameter count, the description covers all necessary aspects: purpose, returned structure (signal map, evidence trail, etc.), async behavior, idempotency, and constraints (≥3 platforms). No output schema is present, but the return structure is described adequately.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context on how parameters relate to the tool's purpose (e.g., 'objective' as deliverable), but does not elaborate on individual parameters beyond what the schema provides. The extra context justifies a 4.

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

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

The description clearly states the tool dispatches to a social listening researcher for multi-platform community-signal interpretation, lists specific use cases (e.g., cross-platform discourse), and explicitly distinguishes from sibling tools like dispatch_qualitative_researcher and dispatch_quantitative_researcher.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 when-to-use guidance (cross-platform discourse) and when-not-to-use with named alternatives. Also advises using the async version when execution exceeds 90 seconds and explains idempotent retry behavior.

Agents often have multiple tools that could apply. Explicit usage 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=false, openWorldHint=true, idempotentHint=false. Description adds context: 'Commits to falsifying conditions before searching' and outlines the return structure (4-axis assessment). No contradictions. Lacks mentions of side effects, but overall good transparency.

Agents need to know what a tool does to the 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 moderately long but every sentence adds value. Front-loaded with purpose, followed by usage examples, then exclusions. Could be slightly more concise, but efficient overall.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 5 parameters (4 required) and no output schema, the description thoroughly explains the tool's purpose, approach, and expected return. It covers when to use and not use, and provides behavioral context beyond structured fields.

Complex tools with many parameters or behaviors need more documentation. 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 parameters are well-documented in the schema. Description adds context for objective and boundaries (e.g., 'one sentence stating what done looks like', 'in scope vs out of scope') but does not significantly extend beyond schema descriptions. Baseline 3 is appropriate.

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

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

The description uses specific verbs and resources: 'Dispatch to TREND RESEARCHER' and 'recency-dominant trajectory investigation'. It lists example questions and explicitly distinguishes from siblings in the NOT section (e.g., dispatch_desk_researcher, dispatch_market_analyst).

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

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

Explicit WHEN section with example queries, and a NOT section naming specific sibling tools for alternative use cases. Clear guidance on when to use this tool versus 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?

Describes async behavior, durable workflow, idempotency, and falsifying conditions, adding value beyond annotations. No contradiction with annotations.

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

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

Detailed but well-structured, front-loading purpose and use cases, then providing exclusions and async specifics. Each sentence contributes value; could be slightly more concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 complexity of async dispatch with many siblings, the description fully covers output format, async mechanism, polling, idempotency, and contrasts with relevant siblings.

Complex tools with many parameters or behaviors need more documentation. 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 5 parameters with descriptions. The description does not add significant new parameter-level information 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?

Description clearly states the tool is for recency-dominant trend investigation, lists specific queries, and distinguishes from sibling tools by naming what it's NOT for, including alternatives.

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

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

Explicitly provides when to use (trend analysis), when not to use (static landscape, entity teardowns, numerical analysis), and names alternative tools. Also explains when to use async version and how to poll results.

Agents often have multiple tools that could apply. Explicit usage 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 idempotentHint=true and destructiveHint=false. The description adds behavioral detail about 'favorited_at is set/cleared in lockstep so the Favorites tab sorts correctly,' which goes 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 sentences, front-loaded with purpose. Every sentence adds value with no redundancy or 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?

For a simple toggle tool with no output schema, the description covers the effect (favorite flag toggle), side effect (favorited_at lockstep), and safety (not destructive). Complete for an agent to 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 description coverage is 100%, so baseline is 3. The description adds value by explaining the lockstep update of favorited_at, which is not in the schema, and clarifies the is_favorite parameter usage beyond the schema 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?

Description clearly states verb+resource: 'Toggle the favorite flag on a saved asset.' This distinguishes it from sibling tools like delete_saved_asset, get_saved_asset, etc., which handle other operations on saved assets.

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

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

Description explains when to use the tool by defining the is_favorite parameter behavior. It does not explicitly mention when not to use or alternatives, but the specificity of the purpose makes usage clear for an AI 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 already declare readOnlyHint=true and openWorldHint=true. The description adds substantial behavioral context: internal routing for PDF vs HTML (PDF uses Anthropic Files API for OCR, HTML uses readability-style extraction), SSRF protection (private IPs and localhost blocked), and the default/range for max_chars. It also notes that output includes 'extracted text content plus metadata'. 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 efficiently structured: a one-sentence purpose, followed by usage examples, explicit exclusions, parameter notes, and a security note. Every sentence serves a distinct purpose without redundancy. It is front-loaded with the core function.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 covers the essential aspects: purpose, use cases, security, and parameter defaults. It lacks explicit detail about the metadata returned (e.g., content type, size, status), but is otherwise complete. The annotations fill gaps for readOnly and openWorld hints. A score of 4 reflects minor omission of output format specificity.

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

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

Schema coverage is 100%, so baseline is 3. The description restates parameter details (url format, max_chars range and default) that are already in the schema. It adds marginal value by mentioning SSRF protection (also in schema) and the token cost implication for higher max_chars, but does not significantly enhance understanding beyond what the schema provides.

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

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

The description uses a specific verb phrase 'Drill into a specific URL after search surfaces it', clearly indicating the tool's action and context. It distinguishes from sibling search tools by explicitly stating it is 'NOT for discovering new URLs' and provides concrete use cases (verifying quotes, reading primary sources, drilling into product pages). This leaves no ambiguity about what the tool does and how it differs from alternatives.

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

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

The description explicitly advises when to use the tool ('after search surfaces it', for verifying quotes, reading full sources) and when not to ('NOT for: discovering new URLs'), and directs to sibling tools (search, search_community, search_research) as alternatives. This provides clear guidance for appropriate invocation.

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

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

Annotations indicate non-readOnly, non-destructive, non-idempotent. The description adds metered pricing (2-5 credits), pre-flight credit reservation with refund, and idempotency key explanation. No contradictions; additional behavioral details are clear.

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

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

The description is well-structured with a clear front-load of purpose and output. While somewhat lengthy, every sentence contributes value. Minor room for tighter wording.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 11 parameters, no output schema, the description covers parameter meanings, prerequisites, pricing, and usage boundaries. Output structure is partially described (hook, body, CTA, visual direction). Missing explicit output schema or sample, but adequate for the 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 coverage is 100%, and the description adds rich semantic detail beyond parameter names: e.g., 'count' rotates tensions/selling points, 'duration' is remix-only, 'voice_mode' explains default and brand usage, 'script_mode' distinguishes blueprint vs remix behavior.

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

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

The description states a specific verb ('generate') and resource ('direct-response video ad scripts'), clearly distinguishing it from sibling tools like decoder_intelligence (source discovery) and create_powersource (brand intel). It details the fusion of a structural source with a brand PowerSource and the output components.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 defines when to use (user requests for scripts, replication of proven winners) and when not to use (source discovery, brand intel extraction). Also specifies prerequisites and guides user to create missing components.

Agents often have multiple tools that could apply. Explicit usage 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 idempotentHint as true. Description adds 'free, read-only' and specifies output contains full body payload, providing some additional context but not extensive behavioral detail beyond what annotations 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 efficient sentences: first states purpose and output, second provides 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?

For a simple retrieval tool with one parameter and no output schema, the description fully covers what it does, what it returns, and how to obtain the required input.

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

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

Single parameter 'id' has full schema description with format and regex. Description reiterates the discovery method, adding value but baseline for high coverage is 3.

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

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

Clearly states the verb 'Get' and resource 'ad formulas preset by id', and specifies it returns the full body payload including framework and agent config. Distinguishes from sibling list tool.

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

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

Explicitly advises to call the matching list tool first to discover ids, and notes it is free and read-only. Lacks explicit when-not-to-use, but context makes it 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 and idempotentHint. Description confirms read-only and adds detail on returned fields and free access, providing useful context 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 sentences, no fluff. Purpose, content, and usage are front-loaded and 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?

For a simple read tool with one parameter and no output schema, the description fully covers what the tool does, what it returns, and when to use it, especially with supporting annotations and sibling list.

Complex tools with many parameters or behaviors need more documentation. 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 description for the single parameter. Description doesn't add extra parameter semantics beyond what schema provides, meeting the 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?

Description clearly states it retrieves a full brand record listing specific fields (name, domain, voice, story, visual identity, counts), distinguishing it from sibling tools like list_brands and get_powersource.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 inspecting brand before running Heist context or reading brand voice when writing copy. Also notes 'Free, read-only' and points to list_brands for obtaining brand_id.

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

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

Description adds context beyond annotations by specifying the returned payload includes 'full body payload (framework, agent config, etc.)'. Annotations already declare readOnlyHint and idempotentHint, so description complements them well.

Agents need to know what a tool does to the 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 two sentences, front-loaded with the main action, contains no filler, and each sentence adds distinct 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 tool with one parameter and no output schema, the description is sufficiently complete: it states the purpose, prerequisite, and nature (free/read-only). Could be slightly more explicit about the return structure, but 'full body payload' 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 100%, and the description merely mentions 'by id' without adding new semantics beyond what the schema provides (UUID format, discover via list). Baseline of 3 is appropriate.

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

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

Description clearly states 'Get one creative agents preset by id, including its full body payload', specifying the verb (get), resource (preset), and scope (by id). It distinguishes from sibling list tool by advising to call the list tool first.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 the matching list tool first to discover ids', providing a clear prerequisite. Also states it is 'Free, read-only', indicating when it's safe 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 give readOnlyHint, idempotentHint; description adds 'Free, read-only' and 'includes its full body payload', extending behavioral detail beyond structured fields. 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 concise sentences, front-loaded with purpose, no redundant words. Every sentence adds value: purpose, what's included, prerequisite, cost/safety.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 fetch tool with one parameter and no output schema, the description fully covers: what, how to get id, what's returned, cost/safety. Complete for context.

Complex tools with many parameters or behaviors need more documentation. 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 100% of the single 'id' parameter with full format description. Description rephrases how to get ids but adds no new semantic meaning beyond schema 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?

Specific verb+resource: 'Get one creative director playbooks preset by id, including its full body payload'. Distinguishes from sibling get_* tools by naming the preset type and payload detail.

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

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

Explicitly advises to 'Call the matching list tool first to discover ids', providing clear prerequisite usage. Adds 'Free, read-only' for safety context, but lacks explicit 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?

Beyond annotations (readOnlyHint, idempotentHint), the description discloses polling interval (15s), return states, completion payload contents, and billing model, all 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?

The description is well-structured into paragraphs with front-loaded purpose, but it is slightly verbose. Every sentence adds value, but could be tighter.

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

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

For a single-parameter retrieval tool with no output schema, the description covers polling logic, response details, integration with other tools, and exclusions, making it very 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 baseline is 3. The description mentions job_id but adds no new constraints or semantics beyond the schema's description and UUID format.

Input schemas describe structure but not intent. Descriptions should explain 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 retrieves or polls a decode bundle for a previously-submitted ad, and explicitly distinguishes from siblings like decode_ad and decoder_intelligence, with specific 'Do NOT use' statements.

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

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

The description provides explicit when-to-use instructions (after decode_ad, every 15 seconds, for re-fetching) and when-not-to-use (discovering or starting decodes) with named alternatives.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds 'Free, read-only' and that it returns 'full body payload', which adds context beyond annotations. However, without an output schema, more detail on the payload structure would be ideal but not critical.

Agents need to know what a tool does to the 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, each serving a distinct purpose: stating the action and giving usage guidance. No superfluous text, front-loaded with the core functionality.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 (1 param, no nested objects, no output schema), the description covers everything needed: what it does, how to use it, and its read-only nature. No gaps are apparent.

Complex tools with many parameters or behaviors need more documentation. 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 'id' has 100% schema description coverage. The description repeats 'Discover ids by calling the matching list_<type>_presets first' which is redundant with the schema's description. No additional meaning is added beyond what the schema provides.

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

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

The description clearly states 'Get one decoded ads preset by id, including its full body payload', specifying the verb (get) and resource (decoded ads preset). It distinguishes from sibling list tools that discover IDs and other get_*_preset tools by covering different preset types.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 the matching list tool first to discover ids', providing clear sequential dependency. Also notes 'Free, read-only' which reassures about side effects, though no explicit when-not-to-use is given.

Agents often have multiple tools that could apply. Explicit usage 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 and idempotentHint; description reinforces that it's a safe, non-destructive poller and explains retry behavior and error_class semantics, adding value 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?

Concise (~5 sentences), front-loaded purpose, then usage pattern and response interpretation. 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?

Fully describes response fields, polling pattern, and error handling. No output schema needed as return values are documented in 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?

Schema coverage is 100% and already explains job_id as the UUID returned by a previous call; description does not add new meaning beyond that.

Input schemas describe structure but not intent. Descriptions should explain 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 gets the current status of a specialist dispatch job started via dispatch_<specialist>_async, distinguishing it from sibling tools like the dispatch_*_async starters.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 instructions: call repeatedly after dispatch_*_async returns job_id, sleep wait_ms_hint, check status, and handle errors (retry on transient/scope/routing, give up on permanent).

Agents often have multiple tools that could apply. Explicit usage 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 and idempotentHint=true. The description reinforces these by calling it 'read-only' and 'Free — no compute cost.' It also explains behavior beyond annotations: org-scoping, resolution of any session_id to the root, and the condition after 'close_session_tree has run.' 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 relatively long but well-structured. It starts with a terse summary, then lists the returned fields. Every sentence adds information. Minor improvement could be trimming redundancy, but it remains efficient for the depth of content.

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

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

Given no output schema, the description comprehensively covers the return values: session rows, depth, parent, agent_kind, node_label, cost_events, self_cost_cents, total compute, tier markup, and credits_charged/refunded. It also explains org-scoping and the condition for authoritative credits. This is fully complete for the tool's purpose.

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

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

Schema description coverage is 100% for the single parameter 'root_session_id'. The description adds value by explaining that it accepts 'any session_id in the tree' and that the handler resolves to the root, which is not in the schema description. This adds practical 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 states it performs a 'read-only walk of a fleet session tree' and returns a comprehensive breakdown including session rows, costs, and credits. It uses specific verbs and resources, and the title 'Get Fleet Cost Breakdown' aligns well. This distinguishes it from sibling tools, none of which are cost-focused.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 to render cost breakdown UIs, audit fleet spend, or verify a session's tree topology.' This provides clear use cases. It does not explicitly state when not to use this tool, but the context is sufficient for an AI agent to infer appropriate scenarios.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds context: "Free, read-only, idempotent — no credits consumed." It also describes what is returned (hook examples, templates, psychological mechanism, performance data) and scope (first 1.5 seconds). 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 well-structured: first sentence states purpose, then filter details, then return info, then usage guidance and exclusions. Every sentence is informative with no waste. 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?

Despite no output schema, the description fully explains what is returned: hook examples, pattern templates, psychological mechanism, and runtime performance data. It also clarifies the source (successful winning ads) and scope (first 1.5 seconds). Complete for a 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 description coverage is 100% with detailed parameter descriptions including examples. The description restates the filters and provides examples but adds little new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: "Browse proven hook patterns from Heista's corpus of decoded winning Meta/TikTok ads." It clearly distinguishes from sibling tools by stating "Do NOT use to decode a specific ad URL — use decode_ad" and "Do NOT use to generate finished scripts — use generate_adscript."

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

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

The description provides explicit usage cues: "Use this when the user asks...", useful before writing a script, and pairs with adformula_intelligence or decoder_intelligence. It also gives explicit when-not-to-use instructions for decode_ad and generate_adscript.

Agents often have multiple tools that could apply. Explicit usage 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 idempotentHint. The description adds that the call is 'Free' and includes the full body payload, which provides additional behavioral context beyond the annotations.

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

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

Two concise sentences that front-load the action and result, with no wasted words. 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 one-parameter tool with no output schema, the description adequately covers purpose, usage, and behavior. The context of sibling list tools is clear, and the return structure is hinted.

Complex tools with many parameters or behaviors need more documentation. 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 parameter is well-documented. The description adds little beyond mentioning the payload, but the schema already guides the agent to use the list tool. Baseline 3 applies.

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

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

The description clearly states it retrieves one static ads preset by ID and includes the full body payload. It distinguishes from sibling list tools and other get tools by specifying the resource type.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 the matching list tool first to discover IDs, and notes that the operation is free and read-only, providing clear context for when and how 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?

Adds progressive polling behavior, billing info (free at submit), and admin-only flag behavior beyond annotations. No contradiction with readOnlyHint/idempotentHint.

Agents need to know what a tool does to the 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 key info front-loaded, but slightly verbose in progressive details. Each sentence is justified, but some rephrasing could improve 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?

Fully describes return values (status vs. complete bundle), progressive data order, and no output schema needed. Comprehensive 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 coverage is 100% with detailed descriptions. The description adds minimal extra detail (admin-only flag context) beyond schema, meeting baseline.

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

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

The description clearly states it retrieves or polls a PowerSource scan, with specific verb and resource. It explicitly distinguishes from sibling tools like create_powersource_* and get_decode.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 exact usage timing (immediately after create call, every 3-5 seconds), re-fetch instruction, and explicit what-not-to-do statements. No ambiguity.

Agents often have multiple tools that could apply. Explicit usage 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 idempotentHint. The description adds behavioral detail: it returns a signed media_url for private storage and enumerates all fields, which goes beyond the annotations without contradicting them.

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

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

Two sentences, front-loaded with verb and resource. Every sentence adds value with no wasted words.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, usage context, and return fields. Annotations confirm safety. It is 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 covers 100% of parameters with format and pattern. The description adds useful context: 'Get from list_saved_assets.' This provides 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 states 'Fetch one saved asset by id' and lists the returned fields. It distinguishes from sibling list_saved_assets by noting it is used for full records when list is too sparse.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 AFTER list_saved_assets to load the full record when the list projection is too sparse.' This provides clear context but does not explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds crucial behavioral detail: missing/cross-workspace ids are silently dropped. This helps the agent understand side effects and error handling.

Agents need to know what a tool does to the 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 waste. Front-loaded with the core action and limit. Every sentence earns its place.

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

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

For a simple tool with one parameter and no output schema, the description is complete. It covers purpose, usage context, behavioral nuances, and post-invocation checks.

Complex tools with many parameters or behaviors need more documentation. 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%, but the description adds meaningful context beyond schema (use case and silent drop behavior). It enhances understanding of the parameter's purpose.

Input schemas describe structure but not intent. Descriptions should explain 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 fetches up to 50 saved assets by id in one round-trip, distinguishing it from single-fetch (get_saved_asset) and list (list_saved_assets) tools. It also gives a concrete use case (resolving saved_asset_picker context input).

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 an agent needs to pull a pre-selected set' and provides an example. It also warns about silent dropping of missing/cross-workspace ids and advises to compare returned items vs requested ids.

Agents often have multiple tools that could apply. Explicit usage 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 details beyond annotations: confirms read-only, mentions 'full body payload' return, and states it's free. 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?

Two concise sentences cover purpose, return content, usage guidance, and safety. 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 read tool with one parameter and no output schema, the description covers all essential information: what, how to call, and what to expect.

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

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

Parameter 'id' is fully described in schema; description adds crucial context on how to obtain it (via list tool), which is not in the schema.

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

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

Clearly states the tool gets a saved visual idea preset by ID and includes its full body payload. Distinguishes from sibling get_*_preset tools by specifying the resource type and mentioning the prerequisite list 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 the matching list tool first to discover IDs. Also states 'Free, read-only' to indicate safety and cost profile.

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

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

Annotations already declare readOnlyHint, idempotentHint. Description adds that it's read-only, free, account-scoped, and archived strategies excluded by default, 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?

Two concise paragraphs with no redundant information. Front-loaded with main action and purpose, followed by necessary nuances.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 lists return fields (buyer profile, tensions, etc.) and clarifies parity with list_strategies and archive behavior, fully preparing 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% and description adds context: powersource_id returns same shape as get_powersource without job_id, include_archived defaults false matching list_strategies.

Input schemas describe structure but not intent. Descriptions should explain 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 reads a creative strategy by powersource_id and compares it to get_powersource, distinguishing it from siblings like list_strategies.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 (when you have a powersource_id and want full strategy) and when not (avoids job_id round-trip needed by get_powersource). Also covers archive handling.

Agents often have multiple tools that could apply. Explicit usage 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, idempotentHint=true. Description adds that it's 'Free, read-only' and includes 'full body payload', which clarifies the return nature beyond annotations. No contradiction with annotations.

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

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

Two sentences: first sentence states the action and return value, second provides workflow guidance and cost hint. No redundant information; every word serves a 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?

For a single-id retrieval tool with no output schema, the description fully covers what the tool does, how to prepare (list first), and what kind of data to expect (full body payload). Combined with annotations, it provides sufficient context for the agent to use 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% with one parameter 'id'. Description adds context on how to obtain the id ('discover ids by calling the matching list_<type>_presets first'), which is not present in the schema's format/pattern alone. This helps the agent understand the parameter's sourcing.

Input schemas describe structure but not intent. Descriptions should explain 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 'Get one visuals preset by id, including its full body payload'. The verb 'Get' and resource 'visual preset' are specific, and the mention of 'full body payload' distinguishes it from simpler list operations. Among sibling tools with similar get_* names, it uniquely identifies this preset type.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 advises to 'Call the matching list tool first to discover ids', which guides proper workflow. Also notes it's 'Free, read-only', indicating low cost and safety. Does not explicitly state when NOT to use it, but the instruction to list first implies the tool requires a known id.

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

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

Annotations already declare readOnlyHint and idempotentHint true, and the description adds 'Free, read-only' which reinforces but does not contradict. It also mentions 'full body payload' giving a hint about the return content, adding some value 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 sentences with no wasted words. The purpose is front-loaded, and each sentence serves a clear function: stating the action and providing usage guidance.

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

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

For a simple get-by-id tool with full schema coverage and clear annotations, the description is complete. It mentions the return content ('full body payload') and the prerequisite, leaving no significant gaps.

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

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

Schema description coverage is 100% and already includes a description of the id parameter including how to discover ids. The description text duplicates this guidance but does not add new semantic 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 states 'Get one visual styles preset by id' with specific verb and resource. It distinguishes from sibling list tools by implying this is for retrieval of individual preset details.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 advises to 'Call the matching list tool first to discover ids', providing clear prerequisite guidance. It lacks explicit when-not-to-use instructions but is sufficient for typical 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 declare readOnlyHint, idempotentHint, and openWorldHint=false; the description confirms 'Read-only, free' and adds behavioral details: mutual exclusion of filters, pagination, and that the data is Heista-curated. 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 extremely concise: two sentences delivering purpose, behavior, and usage guidance. Every word is functional and front-loaded. No wasted sentences or repetitions.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 covers purpose, filter options, pagination, and read-only status. It hints at the use case ('served as a generation parameter'). Could be slightly more explicit about what the returned list contains, 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 has 100% coverage so baseline is 3. The description adds meaning by explaining the filter scope ('same toggle as the in-app library lens') and mentioning that only_workspace/only_official are mutually exclusive, which enhances understanding beyond the schema comments.

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

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

The description clearly identifies the resource as 'Cluster-level structural formulas derived from decoded ads' and specifies it is 'Heista-curated'. The verb 'List' combined with 'Ad formulas' in title makes the action explicit. It distinguishes from siblings by noting the cluster-level and generation parameter nature.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 it is 'Read-only, free' and describes filtering options with mutual exclusivity (only_workspace/only_official) and pagination (limit+offset). It provides clear context for usage but does not explicitly state when NOT to use or compare to alternatives like list_decoded_ad_presets.

Agents often have multiple tools that could apply. Explicit usage 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 idempotentHint=true. The description adds 'Free, read-only. Paginated via cursor.' and lists return fields (asset_id, signed url, type, etc.), providing behavioral context 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?

The description is two sentences, front-loading the action and filters, then providing usage advice and return info. Every sentence adds value with no redundancy or 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 the 7 parameters, no output schema, and presence of annotations, the description covers purpose, filters, usage guidance, return structure, and pagination. It is mostly complete; minor omissions like default ordering do not significantly hinder 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 description coverage is 100%, so the input schema already documents all parameters. The description adds minimal extra value by grouping filters ('Filter by PowerSource... by on-pack product_name...') but does not significantly expand on the schema descriptions. 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 'List images for a brand' and enumerates all filter options, distinguishing it from sibling tools like add_brand_asset or delete_brand_asset. It also provides a concrete use case: 'Use this BEFORE generating any image-based output so you pick from the brand's real assets, not generic stock.'

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 advises 'Use this BEFORE generating any image-based output', giving a clear when-to-use recommendation. It does not explicitly list when not to use it or alternatives, but the sibling tools are distinct (e.g., add/delete/retag). This is nearly excellent usage 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 provide readOnlyHint=true and idempotentHint=true. Description adds detail about return fields, pagination via cursor, and filter options, which goes 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?

Three concise sentences: purpose and return fields, filter options, usage guidance. Every sentence adds value with no redundancy.

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

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

No output schema, but description explains return fields. Covers pagination, filters, and usage context. Minor gap: no explicit mention of error handling or rate limits, but annotations cover safety.

Complex tools with many parameters or behaviors need more documentation. 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 5 params (100% coverage). Description adds extra guidance like using 'indexed' status for fully-processed docs, and explains cursor format. Adds meaning 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 'List indexed brand documents for a brand' with specific verb (list) and resource. It differentiates from sibling read_brand_document by advising to use this tool first to avoid read cost.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 BEFORE read_brand_document to discover what context exists for a brand without paying the read cost.' Also mentions free, read-only, paginated via cursor. Implies alternatives but doesn't cover when not to use beyond that.

Agents often have multiple tools that could apply. Explicit usage 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 idempotentHint, so the description adds context about the include_all parameter and 'free, read-only' nature. 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?

Three paragraphs with useful information, front-loaded with core purpose and usage. Could be slightly more concise but no extraneous content.

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

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

Completely covers what the tool returns (fields listed), how to use it, and distinguishes from related concepts, despite having 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 100%, and description adds meaning by explaining the effect of include_all=true (transient/signal-less drafts) and ties default to UI behavior, going beyond schema 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?

Description clearly states 'List every brand in this workspace' with specific verb and resource, and distinguishes from sibling tools like list_strategies and create_powersource_* by explaining the difference between Brand and PowerSource.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 advises using before creating a PowerSource to avoid duplicates, and for discovering brands for Heist pivoting. Provides example user queries and distinguishes from related tools.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true. Description adds that it is read-only and free, and clarifies the mutual exclusivity of filters, which is beyond what annotations provide.

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

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

Four sentences, each serving a purpose: purpose, scoping, nature (read-only), and filtering. Front-loaded with key information. 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?

Covers listing scope, filtering options, and pagination. Lacks explicit mention of what the output contains (e.g., preset names), but is fairly complete for a list tool without 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?

With 100% schema coverage, baseline is 3. Description adds value by explaining mutual exclusivity of only_workspace and only_official, comparing to a UI toggle, and noting that brand_id only affects workspace presets.

Input schemas describe structure but not intent. Descriptions should explain 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 lists reusable creative agents for handoff targets, distinguishing between workspace and official presets. This differentiates it from sibling tools like list_brand_assets.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 only_workspace vs only_official, notes mutual exclusivity, and mentions paging. However, doesn't explicitly state when not 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?

Annotations declare readOnlyHint and idempotentHint. Description adds valuable context: the role in system prompt, mutuality of filters, scope of brand_id, and that the tool is free. 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?

Description is compact and front-loaded with key purpose. Every sentence adds information, though slightly dense. 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?

Covers all key aspects: resource, behavior, filtering, pagination, and scope. No output schema, but description implies return of playbook presets. Adequately complete for a 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?

Schema coverage is 100%, baseline 3. Description adds meaning: explains mutual exclusivity of only_official and only_workspace, clarifies brand_id scopes workspace presets only, and describes pagination defaults. Adds practical 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?

Description explicitly states the tool lists Creative Director playbooks, explains their role in substituting system prompt layers, and distinguishes between workspace and official scopes. It clearly identifies the resource and action, differentiating from sibling tools like get_creative_director_playbook_preset.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 guidance on when to use (session start, voice/foundation substitution) and how to filter (mutually exclusive only_workspace/only_official, pagination). Lacks explicit when-not or alternatives, but context is sufficient.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds 'Read-only, free' which aligns with annotations but doesn't disclose additional behavioral traits (e.g., rate limits, data freshness).

Agents need to know what a tool does to the 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 four sentences, front-loading the core purpose, then providing key details on data sources, filters, and pagination. Every sentence adds value with no redundancy.

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

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

For a list tool with 5 parameters and no output schema, the description adequately explains data sources, filter options, and pagination. However, it omits return value structure or example usage, which would enhance 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 coverage is 100%, so baseline is 3. The description adds value by explaining that 'only_workspace' and 'only_official' are mutually exclusive and analogous to an in-app UI toggle, which clarifies their usage beyond the schema.

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

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

The description states it lists 'Structural references for script-led Heists' and specifies the data sources, distinguishing from sibling list tools that focus on different preset types (e.g., ad_formula, image_ad_scan). However, it uses jargon that may be unclear to new users.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 filtering with 'only_workspace' and 'only_official' and pagination, but does not explicitly state when to use this tool versus alternatives like 'get_decoded_ad_preset' or other list tools. Usage context is implied rather than stated.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds 'Read-only, free' and pagination details, but does not disclose additional behavioral traits like rate limits or error conditions.

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

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

Three sentences, front-loaded with purpose, no unnecessary words. Efficient and well-structured.

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

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

With no output schema, the description does not detail return format, but the tool is simple and parameters are fully described. Lacks output structure but otherwise 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 coverage is 100%. The description adds context that only_workspace and only_official are mutually exclusive and analogous to an in-app toggle, which goes 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 lists static-ad references for image-led Heists, distinguishing it from sibling tools like list_ad_formula_presets. It uses a specific verb and resource.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 filtering with only_workspace/only_official and pagination, but does not explicitly state when to use this tool versus alternatives. No when-not or comparative 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 indicate read-only and idempotent. The description adds 'Free, read-only, paginated' and explains the data source split (BRIEFS from creator_briefs, others from saved_assets). 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 a single paragraph but packs dense information without redundancy. It is front-loaded with purpose. Could benefit from structuring into bullet points, but 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 11 parameters and no output schema, the description covers the tool's behavior thoroughly: data source differences, pagination, filter options, and recommended use case. It is complete for effective 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 description coverage is 100%. The description adds context beyond schema, e.g., explaining category values, created_by behavior with OAuth vs API keys, and tags_mode default. This 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 it lists saved assets and explains the unified view backing the /assets page. It distinguishes from sibling tools by specifying the scope and the use case before pulling into a Heist.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 'Use BEFORE asking the user what to pull into a Heist', giving a clear usage context. It implies when to use this tool versus others, though it doesn't list alternatives.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds 'Read-only, free' and 'Page with limit + offset,' which are consistent. However, the phrase 'Workspace-only' is slightly misleading because the only_workspace and only_official filters allow toggling scope, contradicting the implication of an exclusive workspace scope.

Agents need to know what a tool does to the 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 extremely concise (two sentences) and front-loaded. Every sentence serves a purpose: identifying the resource, specifying scope/read-only nature, explaining filter usage, and pagination. No superfluous content.

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

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

The tool has no output schema, yet the description does not explain what each returned item contains or the default behavior (e.g., ordering). It covers pagination and filters but lacks details on result format, which is needed for full completeness given the absence of output schema.

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

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

Schema coverage is 100%, so baseline is 3. The description adds minimal parameter value: it notes mutual exclusivity of only_workspace/only_official and likens them to an 'in-app library lens,' but this is not a significant semantic addition 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 lists 'Visual ideas you saved from prior generations.' It specifies the resource (saved visual ideas) and action (list). The mention of 'Workspace-only' and filters distinguishes it from other list tools like list_visual_preset_presets.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 does not explicitly guide when to use this tool vs. its siblings. It provides filter usage details but no alternatives or exclusion criteria. For example, it doesn't differentiate from list_visual_style_presets or list_image_ad_scan_presets, which are similar list tools.

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

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

Annotations already provide readOnlyHint=true and idempotentHint=true, but the description adds valuable context: 'Returns frontmatter only — no body content (use load_skill for that)' and 'Free, read-only'. This goes beyond annotations by specifying the exact scope of the data returned.

Agents need to know what a tool does to the 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 concise: two sentences with clear front-loading of purpose, followed by details on filters and usage guidance. Every sentence adds value, and there is 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?

For a list tool with 3 optional enum parameters and no output schema, the description covers all necessary aspects: what is returned, filters available, the distinction from load_skill, and cost implications. It is fully complete for the agent to understand tool behavior.

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

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

Schema coverage is 100% with descriptions for each parameter, so baseline is 3. However, the description compensates by listing the output fields (name, description, domain, etc.) that are not in the parameter schema, given there is no output schema. This adds value for the agent in understanding the response.

Input schemas describe structure but not intent. Descriptions should explain 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 skills from the Heista skill library, specifying the return fields (name, description, domain, type, version, source_folder) and distinguishes from load_skill by noting it returns frontmatter only. This provides a specific verb and resource, differentiating it from siblings.

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

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

The description explicitly advises using this tool before load_skill to discover available skills without paying the body-read cost, and notes it is free and read-only. This gives clear context for when to use it, though it does not explicitly list when not to use it beyond the load_skill alternative.

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

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

Description adds 'Free, read-only' and 'Paginated via cursor' beyond annotations, which already declare readOnlyHint and idempotentHint. No contradictions; it reinforces and supplements behavioral traits.

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

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

The description is compact (5 sentences) and well-structured, front-loading the main purpose and progressively adding detail. Every sentence provides useful information without redundancy.

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

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

For a list tool without output schema, the description enumerates returned fields and mentions pagination and cost. It could discuss error behavior or empty results, but it is sufficiently complete for typical use.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the context of parameters (e.g., brand_id from list_brands) and the returned fields, which helps 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 it lists all PowerSource strategies for a brand, specifying the verb and resource. It distinguishes from siblings like list_brands by focusing on strategies and adds nuance about product-page strategies and returned fields.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 (to list strategies per brand) and how to use the results (labeling or product-focused generation). Could be improved by explicitly mentioning alternatives like get_powersource for a single strategy, but still clear enough.

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