Siren

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

The description adds behavioral context beyond the annotations: the image is cropped round, the operation takes a few seconds, and the status transitions from cropping to ready. It also adds a consent requirement. This goes beyond the basic readOnly/destructive/idempotent flags.

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

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

Three short sentences, each earning its place: action, behavior/status, and usage policy. Front-loaded with the core purpose, no filler or redundancy.

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

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

For a simple add operation, the description covers the main behavioral outcome and the consent constraint, and an output schema exists. A minor gap is that all parameters are optional, so the description does not clarify whether at least one image source is required, but this is relatively minor given the overall clarity.

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

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

The input schema already provides descriptions for all 5 parameters (100% coverage), so the baseline is 3. The description reinforces the 'face' concept and crop behavior but does not add parameter-specific details beyond what the schema states, nor does it clarify the relationship between image_url and image_base64.

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

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

The description states a specific action and resource: 'Add a face to the people library.' This clearly distinguishes it from sibling tools like list_people, delete_person, and upload_media, leaving no ambiguity about what the tool does.

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

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

It provides clear context for when to use the tool (adding a person to the people library) and an explicit policy condition ('Only upload people who agreed'). It does not explicitly compare alternatives or state when not to use it, but the context is strong enough to guide selection.

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

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

The description discloses that the call does not charge the user (only generates a link) and that credits are delivered in about a minute. This goes beyond the annotations, which only indicate non-read-only and non-destructive behavior, adding valuable timing and side-effect information.

Agents need to know what a tool does to the 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, with three sentences that front-load the main purpose and then explain the process. Every sentence contributes meaningful information, avoiding redundancy.

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

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

The tool has an output schema (not shown but indicated), and the description covers the essential flow: obtaining a link, human payment, credit delivery, and that no charge occurs. For a tool of this complexity, the description is complete and leaves no critical ambiguity for an 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?

The input schema fully describes both parameters (credits and pack_id) with their ranges and pricing, so the description adds no new parameter details. Since schema coverage is 100%, a baseline score of 3 is appropriate; the description does not enhance parameter understanding.

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

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

The description clearly states the verb 'Get' and the resource 'a Stripe checkout link for more credits', making the tool's purpose unambiguous. It also differentiates from sibling tools by noting 'Read the balance on get_account', which clarifies that this tool is for purchasing, not checking balances.

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

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

The description explains the workflow: give the link to the human, they pay on Stripe, and credits arrive in about a minute. It also clarifies that nothing is charged by this call, which is a crucial usage constraint. While it doesn't explicitly mention alternatives, the reference to get_account provides context for related operations.

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

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

Annotations already cover read-only and idempotent hints. The description adds the return shape (ready=true/false plus follow-up questions) and the 'ask' behavior, which goes beyond the annotations. It does not contradict any annotations, and the additional context is useful though not exhaustive.

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

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

Three sentences, each with a distinct purpose: what it does, what it returns, and when to use it. The most critical information is front-loaded, and there is no unnecessary 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?

The tool is simple with one parameter, annotations cover safety, and an output schema exists. The description adequately covers purpose, usage, and return values, leaving no critical gaps for an agent to call it correctly.

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

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

Schema description coverage is 100%, with the 'brief' parameter clearly described as a plain-language request. The tool description does not add extra semantic details beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description states a specific purpose: asking Siren's clarifier whether a brief is specific enough to generate from. It clearly distinguishes itself from siblings by explicitly mentioning its role before create_campaign, making it easy to differentiate.

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

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

It explicitly states when to use the tool: before create_campaign when the request is vague. This names the alternative (create_campaign) and the condition, providing clear guidance without 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 are all generic false hints, so the description carries the behavioral burden. It richly discloses credit costs (image 10, video 25), scheduled sequential posting with the Allow posting requirement, 402 failure when balance is insufficient, deterministic rendering, a 24-hour replay returning replayed=true without new charge, and clean-slate behavior for external brands. This exceeds what annotations provide.

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

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

The description is long but dense, with bold section headers (FILM KNOBS, ANY BRAND) that make it scannable. It front-loads the core purpose and return-and-poll instruction before moving to details, and every sentence adds operational 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 13-parameter creation tool with an output schema, this description is complete: it covers the end-to-end lifecycle, failure mode, pricing, scheduling side effects, media-vs-image behavior, brand override clean-slate rules, and idempotent retries. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds operational nuance beyond the schema: film knobs are ignored by images, output_type requires list_films/describe_film, scheduled_at enqueues sequential posting, and the brand object gets concrete refusal conditions. That extra context earns 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 first sentence names a specific action and resource ('Create a Siren campaign') and describes the exact pipeline: plan, on-brand copy, deterministic render, verify. This clearly distinguishes it from siblings like render_asset or schedule_post without needing an explicit comparison.

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

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

The description gives concrete decision rules: pass output_type to pin a film or omit it, use upload_product_screen for images instead of media, pass brand for non-workspace brands, and poll get_run after creation. It stops short of explicitly contrasting with render_asset or schedule_post, but the workflow guidance is strongly directional.

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

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

Beyond the annotations (non-readonly, non-idempotent, non-destructive), the description discloses real behavioral traits: the operation costs credits, is paid-only, takes about a minute, allows 3 retries, and enforces one mascot per workspace. This is exactly the kind of non-obvious context that helps an agent manage side effects and expectations.

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

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

The description is dense but economical: it front-loads the core purpose and then packs the essential workflow into a single trailing sentence. The semicolon-heavy structure and parentheticals are slightly compressed, but every clause carries useful information and there is no filler.

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

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

The description covers cost, async polling, follow-up actions, retry limits, input modes, and workspace constraints. Given that the input schema is fully documented and an output schema exists, nothing critical is missing for an agent to correctly initiate the flow and hand off to get_mascot/mascot_step.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by grouping parameters into two semantic modes: 'description (note, kind)' and 'reference picture' (which maps to image_url/image_base64). It also confirms that style and name are part of the creation brief without re-listing every schema property.

Input schemas describe structure but not intent. Descriptions should explain 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 by naming the action and resource: 'Start the brand mascot'. It then distinguishes two input modes (description versus reference picture), which clearly separates it from related siblings like get_mascot (polling) and mascot_step (follow-up). This is a specific verb-plus-resource statement with no ambiguity.

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

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

The description gives clear workflow context: call this first, poll get_mascot, show the human, then use mascot_step to keep or retry. It also frames the creation decision via description versus reference picture. It does not explicitly list alternative tools to avoid, but the sequential guidance and 'One mascot per workspace' constraint are enough to guide an 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?

The description goes beyond the destructiveHint annotation by specifying that deletion includes the clip, file, and poster, clearly defining the extent of the destructive operation. This adds valuable behavioral context beyond what annotations declare.

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

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

The description is a single, well-structured sentence that front-loads the action and scope, with no redundant phrasing or filler. It effectively conveys the essential information in a compact form.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 delete operation with one parameter, the description adequately specifies the target and scope. Since an output schema is available, return values are handled separately, and the destructive behavior is already annotated. Minor omissions like irreversibility are covered by annotations.

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

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

The input schema already fully describes the only parameter (video_id as an ID from list_brand_videos), achieving 100% coverage. The description adds no additional parameter details, so the baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Remove' and the specific resource 'a clip from Brand DNA,' with the additional detail that files and poster are included, which distinguishes it from sibling delete tools like delete_media or delete_person.

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

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

The description implies use for Brand DNA clips but does not explicitly contrast it with alternatives such as delete_media. It offers no explicit conditions or exclusions, leaving the agent to infer the appropriate context from the 'Brand DNA' reference.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds valuable nuance beyond the annotations: deletion is limited to workspace uploads, and already-rendered films keep their copy. This explains a potentially surprising side effect without contradicting the schema or 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 filler, and the core action is front-loaded. The first sentence states exactly what the tool does; the second adds the essential scope and side-effect caveat. Every word earns its place.

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

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

For a single-parameter destructive tool with an output schema and annotations, the description covers the essential facts: what is deleted, the source of the URL, workspace scope, and the rendered-film exception. It does not discuss invalid URLs or non-rendered media references, but the output schema and annotations cover enough for correct invocation.

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

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

Schema description coverage is 100% and the sole 'url' parameter is clearly documented as 'The URL upload_media returned (or one from list_media).' The description reinforces this by saying 'delete one photo or video uploaded with upload_media' but adds no new parameter-level 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 uses a specific verb ('Delete') and resource ('one photo or video uploaded with upload_media'), clearly distinguishing it from sibling delete tools like delete_brand_video or delete_product_screen. It also adds scope: only this workspace's uploads.

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

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

The description gives clear context about when this tool applies: deleting media uploaded via upload_media (or listed by list_media). It does not explicitly name alternatives like delete_brand_video, but the scoping statement 'Only this workspace's uploads' and the rendered-film caveat provide meaningful usage boundaries.

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

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

Annotations already communicate that the tool is destructive (destructiveHint=true, readOnlyHint=false), so the major behavioral risk is covered. The description adds the resource scope ('people library') but does not disclose whether deletion is permanent, irreversible, or cascading, which would be useful context for a delete operation.

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

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

The description is a single, front-loaded sentence with no filler or unnecessary detail. It communicates the verb and resource immediately and earns every word.

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

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

For a one-parameter destructive tool with an output schema and a destructive annotation, the description is largely sufficient: an agent understands the action and the schema provides the parameter meaning. An explicit note about permanence or a pointer to list_people would improve it, but these are minor gaps given the annotation coverage.

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

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

Schema description coverage is 100%, and the single parameter person_id is already documented as 'Id from list_people.' The description does not add meaningful parameter semantics beyond this, so the baseline score of 3 applies.

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

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

The description uses a specific verb, 'Remove', and identifies the exact resource, 'face from the people library'. This clearly distinguishes it from sibling tools like delete_product_screen and aligns with the tool name delete_person.

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

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

The description gives no guidance on when to use this tool versus alternatives such as add_person or list_people. No prerequisites, exclusions, or alternative tool references are provided; the only contextual clue is in the schema's person_id description, not in the tool description.

Agents often have multiple tools that could apply. Explicit usage 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 aligns with the destructiveHint annotation and adds valuable context by clarifying that Brand Memory is not deleted. This goes beyond the annotation's simple destructiveness flag, helping the agent understand the precise scope of destruction.

Agents need to know what a tool does to the 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 short, purposeful sentences with zero fluff. The main action is front-loaded, and the clarifying distinction about Brand Memory is placed immediately after, making it highly efficient to parse.

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

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

For a simple destructive operation with a single parameter and an existing output schema, the description is adequately complete. It clearly defines the scope and provides the key clarification about what is not deleted, covering the essential context an agent needs.

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

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

The only parameter, screen_id, is fully described in the schema (100% coverage) as 'Id of the brand asset from list_product_screens.' The tool description adds no additional parameter-specific guidance, so it meets the baseline without enhancing semantics.

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

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

The description clearly states the verb 'Remove' and the resource 'product screenshot from Brand DNA', and explicitly differentiates from deleting the entire Brand Memory. This distinguishes it from potential sibling confusion and leaves no ambiguity about the action.

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

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

The description implies the scope (removes a product screenshot but not Brand Memory) but does not explicitly state when to use it vs. alternatives or name a specific alternative tool. The 'Does not delete Brand Memory' clause offers a weak 'when not' but lacks explicit routing to a sibling 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 already cover read-only and idempotent behavior. The description adds behavioral context by listing the data the tool returns (body schema, reference body, seed envelope, media slots, prefills, override rules), which helps the agent predict what the response will contain. No contradiction with annotations was found.

Agents need to know what a tool does to the 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 information-dense sentence that front-loads the purpose and then lists contents in a structured series, followed by an actionable instruction. It is slightly long but each clause adds distinct value, so it earns a high mark.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 an output schema exists, the description does not need to explain return values. It fully covers what the tool provides, parameter context implicitly, and the critical timing relative to render_asset. The combination of annotations, schema coverage, and description is sufficient for correct invocation.

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

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

The input schema already fully documents the single output_type parameter with a description and example values, so the description does not need to add param details. The description only implies that the output is for one film, which adds little beyond the schema; the schema carries the semantic weight.

Input schemas describe structure but not intent. Descriptions should explain 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 clear verb 'describe' and identifies a specific resource ('one film') while enumerating exactly what the contract contains (body JSON Schema, media slots, brand prefills, override rules). It also distinguishes itself from render_asset by stating it is a prerequisite, which helps separate it from sibling tools.

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

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

The description explicitly states when to call the tool: 'Call it before writing a render_asset body.' This is clear context but does not mention when not to use it or name alternative tools, so it falls short of the full 5-level guidance.

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

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

Beyond the readOnly/idempotent annotations, the description discloses a critical behavioral nuance: empty asset_types/channels/connected_accounts lists mean UNRESTRICTED, not missing, and warns never to stop on them. It also adds plan-tier constraints for film renders, which the annotations alone do not convey.

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

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

Four tight sentences, each earning its place: the first front-loads the tool's purpose, the second gives the invocation order, the third prevents a dangerous misinterpretation, and the fourth states a concrete constraint. No filler.

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

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

For a zero-parameter read-only tool with an output schema and strong annotations, the description covers everything needed to call it correctly: what it returns, when to call it, how to interpret the response, and how plan restrictions affect downstream rendering.

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

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

The tool takes zero parameters and schema coverage is 100%, so there is no parameter documentation burden. The description adds value by listing what the response will tell the agent, but this is not parameter semantics; baseline 4 applies.

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

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

The description names a specific verb and resource ('Get the connected Siren workspace') and enumerates the returned fields: plan, key scopes, auto-post setting, and daily limit. This clearly distinguishes it from sibling tools like get_brand_dna or get_run that target different resources.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 tells the agent when to invoke the tool: 'Call this first to learn what the account can do before generating.' It also gives a decision rule about empty lists being unrestricted, and ties film-render capability to plan tier, so the agent knows how to act on the result.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, and the description adds value by explaining the returned checks and how they should drive next actions. It also clarifies that this is not Brand Memory, which is useful semantic context beyond the structured hints.

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

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

The description is dense but purposeful: it front-loads the core getter, then lists contents, checks, follow-up actions, and disambiguation. The long second sentence is a bit packed, but every clause contributes operational guidance.

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

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

It covers what the response includes, what the checks mean, when to call the tool, and what to do next. With no parameters and an output schema present, there is no missing input or return-shape guidance an agent would need.

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

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

The tool has zero parameters and schema coverage is 100%, so there are no parameter semantics to explain. The description appropriately focuses on output contents and follow-up actions instead of input fields.

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

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

The description names the exact resource (Brand DNA) and the verb (Get), enumerates the returned fields, and directly disambiguates from Brand Memory. An agent can clearly distinguish this read-only getter from update_brand_dna or list-style siblings without opening schemas.

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

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

It explicitly sequences the call: run right after get_account, and if checks indicate issues, fix with update_brand_dna and upload_product_screen or ask the human for the site. This is concrete workflow routing beyond simply saying what the tool does.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds meaningful context beyond that: exactly which fields are returned, that pose frames include URLs, and that a null mascot means none exists yet. No annotation contradiction.

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

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

Two short clauses with no filler; the resource name comes first and the null-handling note is useful. An explicit action verb would improve flow, but the text is efficient.

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

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

With no parameters, safety annotations, and an output schema present, the description covers the essential client-facing behavior: the key fields and the null case. It is sufficient for an agent to invoke correctly; deeper interpretation of the status values is left to the schema.

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

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

The tool has zero parameters, so the 100% schema coverage fully defines the input contract. The description has no parameter-semantics burden and correctly omits parameter discussion.

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

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

The description identifies a clear resource (the workspace mascot) and enumerates the returned data: status, hero picture, tries left, and pose frame URLs. It lacks an explicit verb like 'retrieves' or 'gets', relying on the tool name, so it stops short of a top score.

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

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

No guidance is given for when to call this tool vs. alternatives such as create_mascot or mascot_step. The null-mascot note implies existence checking, but the description never states a selection condition or names any sibling.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful context about the returned metrics but does not disclose behavioral details such as how 'top posts' are ranked, whether limits apply, or how the window affects the top-post selection.

Agents need to know what a tool does to the 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 compact single sentence that enumerates the key output categories without redundancy. It is efficient, though the informal opener 'How the posts did:' is slightly less direct than a more explicit 'Returns post performance metrics' would be.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 one optional parameter, full schema coverage, read-only/idempotent annotations, and an output schema, this is a fairly complete definition for a simple analytics tool. The main missing pieces are sibling differentiation and definition of 'top posts,' but those are not critical given the output schema and annotations.

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

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

The only parameter, window, is already fully described in the input schema ('7d, 30d or 90d'), so schema coverage is 100%. The description adds no additional meaning for this parameter, so the baseline score of 3 applies.

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

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

The description clearly states that the tool reports post performance via totals (impressions, engagement, replies, engagement rate) and top posts by views, likes, and replies. It is clear about the resource and outcome, though it does not explicitly distinguish itself from sibling tools like list_posts or get_run beyond the metric vocabulary.

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

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

There is no guidance about when to use this tool versus alternatives such as list_posts or get_account. It neither provides usage conditions nor mentions which sibling tool to choose for other post-related needs.

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

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

Annotations already signal read-only, idempotent, non-destructive behavior voice; the description goes well beyond by explaining status semantics, poll_after_seconds, progress, eta_seconds, film_check advice, notices behavior, caption handling, and posts[] after post_run. This is rich behavioral context that structured fields cannot convey.

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

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

The description is long but front-loaded with the core purpose and immediate polling guidance. Every sentence adds useful operational detail rather than filler. The density and single-paragraph structure make it slightly harder to scan, so it earns a 4 rather than a 5.

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

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

Given the tool's complexity and the presence of an output schema, the description thoroughly covers polling behavior, terminal status, field semantics, human-decision advice, re-render constraints, notices, captions, and post-run posts data. Nothing critical is missing.

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

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

The input schema already covers the single parameter with 100% coverage and specifies that run_id comes from create_campaign, render_asset, or list_runs. The description reinforces this context but does not add new parameter-level meaning beyond what the schema provides, so the baseline of 3 applies.

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

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

The description opens with a specific verb+resource: 'Get one run by id', followed by a concrete list of what is returned (status, output text, asset URLs, caption, error). This clearly differentiates it from list_runs and other sibling tools.

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

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

It gives explicit when-to-use guidance: poll after create_campaign or render_asset until status is terminal, and wait poll_after_seconds between polls. It doesn't explicitly state when not to use it or name an alternative tool, so it stops short of a full 5.

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

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

Annotations already establish that this is read-only, idempotent, and non-destructive. The description adds the useful scoping fact that only brand-owned clips in Brand DNA are returned and that scan_status is part of the output, but it does not disclose ordering, pagination, or access expectations.

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

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

A single front-loaded sentence states the scope before listing the output fields, with no filler or repetition of schema information. It is compact and easy to scan.

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

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

Given zero parameters, read-only annotations, and a separate output schema, the description covers the non-obvious scope and the important content of the response. Nothing critical appears missing for an agent to invoke it correctly.

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

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

The tool accepts no parameters, so parameter semantics are trivially complete. The description's field list adds useful context about the response payload but is not needed to clarify parameter meaning.

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

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

The description anchors the tool to a specific resource—brand-owned clips in Brand DNA—and enumerates the returned fields. The tool name supplies the 'list' operation, and the description's scope clearly distinguishes it from upload/delete and general media list 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?

There is no explicit guidance about when to use this tool versus siblings like list_media or upload_brand_video. The phrase 'when to use it' refers to a field within each clip, not to the tool's invocation context, so the intended use must be inferred from the name.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses important behavioral constraints: it is paginated (one ranked page at a time), films are ranked by job/goal fit, every film here is 25 credits, platinum films (50 credits) are excluded, and video renders require Pro or above. It also explains the output structure (each film says what it is, when to hire it, length, shapes, fits_this_brand with missing info, and made_recently). 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 relatively long but information-dense; each sentence adds a new capability or constraint. It front-loads the core concept (film library, ranked page) and then layers pagination, filters, pricing, and alternative tools. Some metaphorical language ('hire from the top of the page') could be more concise, but it remains efficient and structured. Not verbose enough to be a 3, but not optimal enough for a 5.

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

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

Given that the tool has an output schema (though not shown) and annotations for read-only and idempotent, the description covers all essential aspects: pagination mechanics, ranking logic, filters (aspect, search, narrated, max_seconds), all films option, catalog file alternative, credit costs, plan requirements, and pointers to related tools. It leaves nothing critical missing for an agent to call it correctly.

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

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

The schema already describes all 10 parameters with 100% coverage, so the baseline is 3. The description adds value by explaining how parameters interact: 'pass job and the human's goal', 'Page on with next_page', 'all=true' for all, and 'search= finds films by word'. It also clarifies the 'job' concept (shelf) and the 'goal' as the human's words. This cross-parameter usage guidance goes beyond the schema and earns 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 that this tool lists the film library, one ranked page at a time, and that films sit on job shelves, pass job and goal to rank them. It distinguishes itself from sibling tools by explicitly pointing to list_platinum_films for platinum films and describe_film for the body. The verb 'list' and resource 'films' are clear, with a strong metaphor that conveys the ranking and filtering behavior.

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

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

The description provides explicit usage instructions: pass job and the human's goal, page on with next_page, use all=true for all films, or fetch the catalog file. It also tells when NOT to use it: for platinum films use list_platinum_films, and for the body of a film use describe_film. It mentions search= for word matching. This gives clear direction on when to use this tool versus its siblings.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds useful behavioral context beyond annotations: it returns photos and videos sorted newest first and includes URLs, which is meaningful for an agent deciding how to use the result.

Agents need to know what a tool does to the 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 short sentences with no wasted words. The primary content and ordering are front-loaded, and the reuse guidance is a compact, purposeful addition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 parameters, strong annotations, and an output schema present, the description fully covers the tool's role and how its results should be used. Nothing required for correct invocation is missing.

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

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

The tool has zero parameters, so the schema leaves nothing to explain. The description's mention of URL output effectively covers what an agent needs to know about the tool's interface.

Input schemas describe structure but not intent. Descriptions should explain 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 clear resource ('photos and videos uploaded with upload_media'), a clear ordering ('newest first'), and a clear return characteristic ('with their URLs'). It also distinguishes itself from the upload path by naming upload_media as the source.

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

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

The description gives concrete downstream guidance: reuse a URL in create_campaign media or a film body. It implies this tool is for retrieving previously uploaded media rather than uploading or listing other entity types, though it does not explicitly exclude sibling 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description does not contradict them. It adds content context about the fields but no additional behavioral traits such as pagination, ordering, permissions, or 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 a single efficient sentence with a front-loaded resource header and a compact parenthetical field list. It is concise and has no filler, though the phrasing around 'team faces Siren can put in stills' is somewhat awkward.

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

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

For a zero-parameter, read-only list tool with an output schema and strong safety annotations, the description is nearly complete. It gives the domain and content, while output format and side effects are already covered by the output schema and annotations.

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

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

The input schema has zero parameters, so schema description coverage is trivially complete. The parenthetical field list refers to record contents rather than invocation parameters, so there is no parameter meaning the description needed to clarify.

Input schemas describe structure but not intent. Descriptions should explain 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 is a noun phrase ('The people library') rather than an explicit action statement; it never says 'list' or 'retrieve.' It does provide useful resource detail and distinguishes people from other listable resources, but the operation itself is left to the tool name.

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

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

No explicit when-to-use guidance or alternative tools are mentioned. The 'team faces Siren can put in stills' phrasing implies a data-domain use case, but the description does not say when to prefer list_people over add_person, delete_person, or the other list_* siblings.

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

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

The description adds significant behavioral context beyond the readOnly/idempotent annotations: the 50-credit cost, the 402 error on complimentary plans, id ending in -plt, and the MM/MVM voice mode distinction. This goes well beyond the annotations and helps the agent anticipate real-world 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 dense and information-rich, with every sentence contributing useful guidance. It is not as crisp as a two-sentence definition, but the extra length is justified by the pricing, plan, and work-flow details. A bit more structure or bullet-like separation would improve scannability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 that this tool has no parameters and an output schema exists, the description covers the essential selection and invocation context: when to use it, what it costs, plan limitations, error behavior, and how to proceed after listing. Nothing critical for correct use is missing.

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

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

The tool has zero input parameters, so there is no parameter surface for the description to clarify; an empty schema already communicates this. The description's additional notes about credits, plans, and ids are not parameter-level but are still useful context. Baseline 4 is appropriate for a no-parameter tool.

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

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

The description clearly identifies the tool as listing platinum films: 'the platinum shelf: studio-grade films'. It differentiates from list_films by naming the normal-film sibling and explaining the credit cost difference. The verb 'list' and resource 'platinum films' are explicit 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?

The description gives explicit when-to-use guidance: 'Offer one only when the human is making a big launch they genuinely want to go far', and explicitly routes everyday/normal-budget cases to 'list_films'. It also provides operational guidance like saying the price before rendering and using describe_film for the body.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful context by explicitly noting that both sent and queued posts are included and that counts by status are returned, going beyond what annotations provide.

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

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

The description is a single sentence that immediately states the core purpose and then lists key output attributes. It is concise, front-loaded, and contains no filler, making it efficient for an agent to parse.

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

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

With an output schema present and annotations covering safety, the description provides a solid high-level overview of what is returned. It does not explicitly state that it returns a list, but that is implied by the verb 'list' and the schema. Missing details like error conditions are minor for a read-only listing tool.

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

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

The schema provides complete descriptions for both parameters (limit and offset), including defaults, ranges, and ordering. The description adds no additional parameter-specific information, so it relies on the schema's coverage, which is sufficient.

Input schemas describe structure but not intent. Descriptions should explain 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 (list) and resource (posts), and specifies scope ('every post Siren sent or queued') along with the returned fields (platform, status, live URL, time, counts). This distinguishes it from other list tools targeting different resources like films or media, making its purpose unambiguous.

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

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

The description implies use for viewing posts, but offers no explicit guidance on when to choose this over alternatives or any exclusions. With many sibling list tools, a brief mention of when to use this tool (e.g., 'for post history') would improve clarity, but the resource name itself conveys primary usage.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful context like the Brand DNA scope and scan_status lifecycle values, but it does not disclose pagination, sorting, or whether the full set of assets is returned in one call.

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

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

The first clause is front-loaded with the purpose, and the second clause compactly lists the row fields. It is not bloated, though the field list may partially duplicate the output schema and could be trimmed without losing clarity.

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

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

For a no-parameter, read-only list tool with strong annotations and an output schema, the description is largely sufficient: it states what is listed and the shape of each row. It stops short of fully complete by not addressing pagination or how this tool relates to get_brand_dna.

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

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

The tool has zero parameters and the schema covers 100% of them, so there is no parameter ambiguity to resolve. The description's field list describes output rows rather than inputs, and the baseline for zero-parameter tools is appropriately strong.

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

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

The description states a specific action ('List') and a specific resource ('brand assets in Brand DNA'), then further delimits the scope to product photos, app screenshots, and packaging. The row-field enumeration makes the purpose concrete and distinguishes it from mutation siblings like update_product_screen and delete_product_screen.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 say when to prefer this over alternatives such as get_brand_dna, nor does it give exclusions or context. The imperative 'List...' implies the basic operation, but there is no explicit guidance about when this tool should be selected or avoided.

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

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

Annotations already signal readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context beyond those annotations: newest-first ordering, the fields returned, and pagination behavior via offset. 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?

A single front-loaded sentence covers the action, resource, ordering, returned fields, and pagination guidance without wasted words. It is easy to scan and fully informative.

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

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

For a read-only, idempotent list operation with an output schema, 100% schema-covered optional parameters, and rich annotations, the description is complete. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, and both parameters already have clear descriptions. The description reinforces paging with offset but does not add meaningful semantics beyond what the schema provides, so the baseline 3 is appropriate.

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

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

The description states a specific verb ('List'), a clear resource ('workspace's generation runs'), ordering ('newest first'), and the returned fields. It is easily distinguished from siblings like list_films, list_media, and list_posts.

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

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

The description gives clear usage context for listing generation runs and explicitly instructs paging with offset to retrieve all runs. It does not explicitly name alternatives or when-not-to-use it, but the resource scope is specific enough for an agent to select it correctly.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive. The description adds useful behavioral context: ranking by goal and section, the made_recently preference, and an alternate bulk endpoint. The made_recently reference is somewhat cryptic but still extends beyond the annotations.

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

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

The description is reasonably compact but includes stylized, somewhat tangential phrasing like 'Siren picks one when you don't' and the cryptic 'made_recently' rule. It is front-loaded with the core concept, but not 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 read-only, well-schematized listing tool with an output schema, the description covers ranking behavior, section shelves, downstream usage, and an alternative for getting the whole library. Pagination detail is left to the schema, which is acceptable here.

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

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

The input schema already documents all seven parameters with 100% coverage. The description adds meaning by explaining how goal and section affect ranking, how to use a returned style id downstream, and when to prefer the full-file endpoint. This goes beyond simply restating the schema.

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

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

The description clearly identifies the tool as the style library and describes it as returning ranked, paginated styles. It distinguishes the resource (painted stills/styles) from sibling list_* tools, though it uses stylized language rather than an explicit 'list styles' statement.

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

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

The description gives practical guidance: pass section and the human's goal, prefer section + page or the styles.md file for full-library needs, and use the returned style id in create_campaign. It does not explicitly compare against alternative sibling tools, but the usage context is clear.

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

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

Annotations are all false, so they provide no safety or side-effect information. The description adds useful behavioral context by warning that 'keep' builds the entire sheet and requires human confirmation, implying a consequential, non-idempotent action. However, it does not disclose the behavioral implications of retry or pose beyond what the schema states.

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

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

The description is two sentences with no filler. The purpose and the branch options are front-loaded, and the human-approval warning is placed where it matters. 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?

With 5 parameters, a full input schema, and an output schema present, the description covers the workflow-critical guidance: the need to ask the human before 'keep'. It is sufficient for invoking the tool correctly, though it could more explicitly state when to choose mascot_step over a sibling 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 adds no further detail about note, label, prompt, or with_model; it only paraphrases the action options already covered by the schema. It is adequate but does not enrich parameter understanding.

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

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

The description uses an active verb ('Move the mascot on') and immediately lists the three possible actions: keep, retry, and pose. This makes the tool's role clear and sets it apart from simple get/create/render siblings, though it relies on the schema to fully define the actions.

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

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

The description clearly instructs to ask the human before using 'keep' because it builds the whole sheet, which is important workflow guidance. It also presents the three branches of use, but it does not explicitly contrast the tool with sibling tools such as create_mascot or render_asset.

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

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

It clearly discloses the external, public nature of the action, the authorization prerequisite, the queued ~two-minute cancellable publish window, and the exact polling path to the live permalink. This goes well beyond what the annotations (destructiveHint/openWorldHint) already convey.

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

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

Four sentences, front-loaded with the highest-stakes fact (live public distribution), followed only by necessary operational constraints and outcomes. No filler or redundant restatement of the tool name.

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

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

The description covers the external effect, user confirmation, authorization, queue behavior, cancellation, and the polling path to the output permalink. Since an output schema exists, it need not restate return values, and nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description's caption note mostly repeats the schema's 'verbatim / omit and Siren writes it' semantics, and it adds nothing new for run_id or platform. No meaningful value beyond structured input.

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

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

The description names the action ('Post') and the resource ('a finished run's assets' to the workspace's CONNECTED SOCIAL ACCOUNT), making the tool's scope immediately clear. It also distinguishes itself from asset-generation or campaign tools by stressing that this is live, public distribution.

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

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

The description gives strong context: confirm with the user before calling, only works if the grant allowed posting, and poll get_run afterward to observe the result. It does not explicitly contrast with sibling schedule_post for advance scheduling, so it stops short of a full when/when-not routing statement.

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

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

Annotations provide no safety signals, so the description carries full behavioral weight. It discloses the Director's Brand DNA editing behavior, that media is never touched, that a `director` field reports changes, and that incompatible films return 422 with fix and films_that_fit. It also explains brand_override clean-slate semantics and upload requirements.

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

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

The description is long but densely organized into purpose, routing, item format, return flow, Director behavior, and brand override. It is front-loaded with the core action and the critical films-only constraint, and every section adds necessary operational detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 when to use the tool, what inputs are valid, what happens during rendering, how errors are surfaced, how to poll results, and edge cases like rendering for another brand. With an output schema present, it appropriately focuses on behavior and workflow rather than restating return 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?

The schema only documents `name` and a generic `items` array with additionalProperties, leaving nested item fields undocumented. The description defines the item shape and explains `direction`, `music`, and `brand_override` with concrete examples and behavioral consequences, fully compensating for the schema gap.

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

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

The description opens with 'Render films from pre-formed SirenSeed bodies (advanced)', giving a specific verb, resource, and scope. It then explicitly differentiates from siblings by stating films only and routing images to create_campaign with asset_type=card.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 routing: 'for any image, ad or creative call create_campaign with asset_type=card' and 'Prefer create_campaign unless the user has concrete seed JSON.' It also advises waiting poll_after_seconds before get_run and requires media URLs to come from upload_media.

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

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

The description adds meaningful behavioral context beyond the annotations: posts 'fire sequentially,' the time is 'shown in the customer's local timezone,' and it names an authorization requirement ('Requires Allow posting'). It does not contradict the annotations, and the destructiveHint is not undermined by the text.

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

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

The description is compact and front-loaded with the core purpose, then provides practical usage and behavioral details in a few short sentences. 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 5-parameter tool with an output schema, annotations, and sibling separation, the description covers purpose, prerequisites, behavior, and alternatives. Nothing critical is missing for an agent to select and invoke this tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds a little extra context such as 'finished run' and platform values, but it mostly restates information already in the schema (platforms, scheduled_at, timezone).

Input schemas describe structure but not intent. Descriptions should explain 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 action and resource: 'Schedule a finished run to post at scheduled_at (ISO-8601).' It clearly distinguishes the tool from its sibling post_run by stating 'Prefer this over post_run when the user names a time,' so an agent can tell them apart.

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

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

The description explicitly says when to use this tool over post_run ('when the user names a time'), and points to create_campaign as an alternative ('On create_campaign you can pass scheduled_at instead'). It also states a prerequisite ('Requires Allow posting').

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

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

Beyond the annotations, the description discloses that the call creates a profile, returns specific URL artifacts, and that enabling social_account_ids triggers publishing and requires the Allow posting permission. It does not go into failure modes or side effects beyond publishing, but none of the annotations are contradicted.

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

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

Three short sentences, each earning its place: the core action, the returned artifacts, and the important publishing caveat. The purpose is front-loaded and no filler is present.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 create tool with only four parameters, full schema coverage, an output schema, and sibling differentiation, the description covers the essential call-time knowledge: what is created, what is returned, and the one high-stakes behavioral toggle. Nothing critical is missing.

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

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

The schema already covers all four parameters, so the baseline is 3. The description adds real semantic value for delivery.social_account_ids by explaining that it enables social delivery and that publishing then requires Allow posting, which is not inferable from the bare schema type.

Input schemas describe structure but not intent. Descriptions should explain 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 a specific action and resource: 'Create a Studio profile on this API key.' It also names the returned artifacts and the social-delivery mode, which separates it from sibling studio tools like studio_card or studio_schedule.

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

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

The intended use is clear: call this to create a Studio profile and obtain integration hook URLs on the current API key. It also explicitly states the condition and permission needed for social delivery ('requires Allow posting'), though it does not name alternative tools or when-not-to-use scenarios.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, non-idempotent, closed-world), but the description adds real value beyond them: rendering is deterministic React with 'no paint', and posting is an optional side effect performed after render that returns a post url. It does not mention auth requirements or rate limits, and the side-effectful posting to an external channel sits awkwardly beside openWorldHint=false, but it is not a direct 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?

Three short sentences with no filler, front-loading the action and the return values immediately. Slightly clipped phrasing ('no paint') trades a little clarity for brevity, keeping it just under a 5.

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

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

An output schema exists, so the description needn't explain return values, and 100% schema coverage handles parameters. What's missing is the routing context an agent needs against seven sibling rendering/posting tools, which leaves the definition adequate but with a clear gap for an 8-parameter tool with a nested body object.

Complex tools with many parameters or behaviors need more documentation. 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 every parameter is already documented in structured form, and the description only re-states the 'type + body' pairing. Baseline 3 applies because the schema does the heavy lifting and the description adds no format, enum, or constraint detail beyond it.

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

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

States a specific verb and resource ('Render a Studio data card from a type + body') and names the two required inputs, so the agent knows the core operation. It does not explicitly differentiate itself from siblings like render_asset or studio_automate, which also produce visual output, so it falls short of a 5.

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

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

The description never says when to use this tool instead of render_asset, studio_automate, studio_schedule, or post_run, all of which are plausible alternatives in the sibling list. Only an implied scenario ('optional live post after render') is present, with no exclusions or routing guidance.

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

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

Annotations cover the safety profile (destructiveHint=true, openWorldHint=true, idempotentHint=false), and the description adds the two-phase render-then-queue behavior. But it omits important context: what happens if rendering succeeds and queueing fails, whether the scheduled post can be cancelled, which platforms are supported (left to schema), and auth requirements. For a destructive, open-world write tool this is thin but not misleading.

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

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

A single sentence that front-loads the render step and then the queue step. No filler; every word earns its place.

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

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

This is a destructive, open-world composite tool with a nested body object, per-platform targeting, and timezone handling, yet the description is one sentence. It doesn't explain the relationship between output_type and body, the platform list values (schema only enumerates them in a description, not an enum), or what the tool returns despite having an output schema. Given the complexity and the destructive hint, more context is warranted.

Complex tools with many parameters or behaviors need more documentation. 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 in the schema. The description names scheduled_at only as part of the flow, adding no syntax, format, or constraint detail beyond what the schema provides. Baseline 3 is correct when the schema does the heavy lifting.

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

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

States a specific two-step action: render a Studio card, then queue a ScheduledPost. The resource (Studio card / ScheduledPost) and the combination is clear. However, it doesn't distinguish itself from siblings like studio_card or schedule_post, which appear to be the constituent operations.

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

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

No when-to-use guidance, no mention of alternatives such as calling studio_card and schedule_post separately, no preconditions. The agent has to infer that this is a convenience wrapper. Nothing tells it when this tool is preferred over the sibling primitives.

Agents often have multiple tools that could apply. Explicit usage 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, non-destructive, closed-world, so the safety profile is covered. The description reinforces this with 'List' and mentions the return shape, but adds nothing beyond what structured fields plus the output schema 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?

Two short sentences, front-loaded with the verb and resource, then the routing rule. Every clause earns its place.

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

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

Complete for a no-arg read tool: the annotations cover safety, an output schema covers the return shape, and the description covers purpose plus the ordering relationship with studio_card. Nothing an agent needs 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?

Zero parameters, so the baseline of 4 applies. No param info is needed and none is provided; the description correctly spends no words on parameters.

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

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

States a specific verb (List) plus resource (Siren Studio's 33 React data-card types) and enumerates the returned content (family, description, body schema). Clear enough that it distinguishes from siblings like studio_card, which it explicitly references.

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

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

Gives an explicit when-to-use ('Use this before studio_card') tied to a concrete condition ('so the body matches'). It names the alternative tool and the sequencing rule, leaving nothing to inference.

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

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

The description discloses key behavioral details beyond the annotations: nested bags (offer, product_map, icp) merge rather than overwrite, only provided keys change, and Brand Memory is untouched. This goes beyond the provided annotations, though it doesn't cover output/return behavior or failure cases.

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

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

Three short, information-dense sentences with no filler. The patch semantics, merge behavior, and concrete examples are front-loaded and directly useful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 patch tool, the description covers semantics, nested merge behavior, and out-of-scope side effects. It does not describe the return value, but the input schema and provided examples make the tool sufficiently actionable.

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

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

The schema already documents the 'fields' object and nested merge behavior, and the description adds concrete examples and the list of valid nested bags (offer, product_map, icp), giving practical parameter context beyond the schema alone.

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

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

The description opens with a clear verb-resource pairing: 'Patch Brand DNA.' It specifies partial updates ('Send only keys to change') and defines the object being modified, clearly distinguishing it from read operations like get_brand_dna.

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

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

It gives strong usage context: patch semantics, nested merge behavior, and an explicit exclusion ('Does not read or write Brand Memory'). It stops short of naming sibling tools as alternatives or giving explicit when-to-use vs. get_brand_dna guidance, but the context is clear enough.

Agents often have multiple tools that could apply. Explicit usage 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 this is a write operation (readOnlyHint=false). The description adds nothing beyond the basic edit verb; it does not disclose whether updates are partial (only provided fields) or full replacement, nor any side effects or idempotency behavior. With minimal annotations, the description should carry more burden but does not.

Agents need to know what a tool does to the 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 sentence with no waste, front-loading the action and resource. It lists the editable fields concisely. Slightly listy but acceptable for clarity.

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

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

For an 8-parameter mutation tool with an output schema, the description is minimal. It does not clarify partial vs full update semantics, does not mention any constraints or validation, and omits the need to first fetch screen_id via list_product_screens (though schema mentions it). An agent would need to infer behavior from the schema alone, which is not ideal.

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

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

Schema description coverage is 100%, so all parameters have descriptions. The tool description adds only a loose grouping of 'screenshot tags' (screen_type, device, theme), which is marginal value. It does not explain the relationship between screen_id and list_product_screens, which is already in 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 clearly states the verb 'Edit' and the resource 'existing brand asset', listing the specific fields to be modified. This distinguishes it from siblings like upload_product_screen (create) and delete_product_screen (destroy), and from update_brand_dna (different asset 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?

The description gives no explicit guidance on when to use this tool versus alternatives. It does not mention that screen_id must be obtained from list_product_screens, nor does it state any exclusions or conditions. The usage context is only implied by the verb 'Edit'.

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

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

Annotations only indicate non-read-only, so the description carries the burden. It discloses that Gemini reads frames and auto-generates metadata, that scanning takes about 15 seconds, that callers should poll list_brand_videos, and that films reference the video by name. This is meaningful behavioral context beyond the bare 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 compact and front-loaded, with the core purpose in the first sentence and supporting behavioral detail in the following sentences. Each sentence contributes either usage context, processing behavior, or differentiation. It is slightly dense, but not padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 six optional parameters and an output schema, the description sufficiently covers the tool's behavior, asynchronous scanning, and how the asset is later used. It would benefit from explicitly noting the URL/base64 choice or size limits, but those are already captured in the input schema, so no critical guidance is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds some nuance by explaining that even without a description, Gemini auto-generates 'what it shows, when to use it, tags and the best moments,' which maps conceptually to the use_when, tags, and description parameters. However, it does not add new per-parameter semantics beyond the schema.

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

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

The description opens with a specific verb and resource: 'Add a product demo, walkthrough or footage to Brand DNA.' It clearly distinguishes itself from sibling upload tools by explaining that videos belong to films and stills come from pictures, so an agent can separate this from upload_media or upload_logo.

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

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

The description gives clear context: use it to add video assets to Brand DNA, and films will play it when a brief names it. The final sentence 'Videos are for films; stills are painted from pictures' provides a useful exclusion against image uploads, though it does not explicitly name alternative tools or state when not to use it.

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

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

Annotations are sparse (all false hints), so the description must carry the behavioral burden. It adds a meaningful side-effect disclosure: the logo is used by every render, signaling a persistent, workspace-wide change. It does not detail overwrite behavior or what happens when both image fields are null, but the major behavioral fact is stated.

Agents need to know what a tool does to the 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 clean sentences with zero filler. The purpose is front-loaded and the impact statement earns its place by communicating a crucial 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 three-parameter, all-optional tool with an output schema, the description plus schema is mostly sufficient. The only notable gap is not stating what occurs if both image_url and image_base64 are null, or whether an existing logo is replaced. These are minor for the common intended 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%, and the input schema already explains variant, image_url, and image_base64 with defaults. The tool description adds no additional parameter-level meaning, such as how to choose between URL and base64, so the baseline score of 3 is appropriate.

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

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

The description identifies a specific verb and resource: "Set the workspace logo in Brand DNA." The added sentence "Every render uses it" clarifies the logo's scope and impact. It does not explicitly distinguish itself from siblings like upload_media or update_brand_dna, but the purpose is clear.

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

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

The description implies when to use this tool: when you need to set the persistent workspace logo. "Every render uses it" hints that this is a global brand asset rather than a one-off media upload. However, it gives no explicit when-not-to-use guidance or alternatives, leaving some routing ambiguity against sibling tools.

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

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

Beyond the minimal annotations, the description discloses content-hashing/deduplication, workspace-owned URL output, direct renderer consumption, and strict format/size limits. This gives the agent meaningful behavioral expectations that annotations alone do not provide.

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

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

Five compact sentences deliver the core action, output, usage context, format limits, and deduplication behavior with no redundancy. The most important fact (what the tool stores and returns) appears immediately.

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

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

The description, combined with fully documented parameters and an output schema, covers the essential invocation details: accepted input forms, limits, and where the result belongs. It omits edge cases like passing both url and base64, but the schema already hints at the either/or relationship.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value by clarifying the url/base64 mutual-exclusion and the practical format and size constraints that apply to media bytes. This goes beyond mere restatement of parameter names.

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

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

The description states a specific verb/resource: storing a photo or video from https or base64. It also situates the tool within the workflow by noting the returned URL goes into film-body media slots, distinguishing it from sibling upload/render tools.

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

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

The description gives clear context for when to use the tool — preparing media for a film body — and even points to describe_film for slot names. It does not explicitly name sibling tools like upload_product_screen or render_asset to state when not to use them, so it misses full exclusion guidance.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, so the description doesn't need to restate mutation. It adds valuable behavioral context: the asynchronous scan flow, the ~8 second transition, the no-read behavior when description is set, and the free-text nature of kind. It doesn't explicitly state whether repeated uploads overwrite or create duplicates, but the overall behavioral disclosure is strong.

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

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

The description is well-structured with a clear lead sentence, a bulleted two-mode breakdown, and a closing clarification. It is longer than the minimum but every sentence earns its place; the only minor inefficiency is the slightly repetitive phrasing around the two filing modes.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 10-parameter tool with no required parameters and an output schema, the description covers the key decision points: how to provide the image, what happens in each mode, how to track completion, and which parameters are conditional. The output schema exists, so return values don't need to be spelled out. Nothing critical is missing for an agent to invoke this correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the interaction between parameters: description suppresses the read, image_url vs image_base64 are alternatives, and kind/use_when/tags are auto-generated when only the file is sent. It also clarifies that screen_type/device/theme are only relevant for device-framed screenshot masters, which the schema alone doesn't convey.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Upload a brand asset ... into Brand DNA and store it on R2') and immediately distinguishes the two filing modes. It clearly separates this tool from siblings like update_product_screen and list_product_screens by naming the upload-and-store behavior and the polling target.

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

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

The description gives explicit when-to-use guidance: it explains the two ways to file an asset, when Gemini reads the picture versus when Siren trusts the words, and tells the agent to poll list_product_screens while scan_status goes scanning → ready. It also clarifies that screen_type/device/theme only matter for device-framed screenshot masters, which prevents misuse.

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