Picsart GenAI

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description reinforces these by stating 'Read-only; spends no credits and works without authentication'. It adds behavioral context: the widget sandbox blocks non-Picsart URLs, returns a JSON message with user actions, and requires the agent to act on the feedback. This enriches the annotation-provided safety profile with practical interaction details.

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 approximately 150 words, well-structured with a clear lead sentence, followed by a usage flow, constraints, output description, and action. It is front-loaded with the core purpose. While every sentence is useful, a slight reduction in redundancy (e.g., the output description could be more concise) would improve conciseness. Overall, it earns its length.

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

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

Given the tool's complexity (4 parameters, 2 required, no nested objects) and the presence of annotations and an output schema, the description covers all necessary aspects: purpose, when to use, how to use, constraints, expected output, and post-invocation actions. The flow from generation to review to acting on feedback is fully described. No gaps remain for an agent to misuse the 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 high. The description adds value by explaining the UI context of parameters: 'purpose' is 'Shown as the board's heading', 'notes' is 'One line of guidance', and 'candidates' must be Picsart-hosted URLs (max 12). It also clarifies the effect of 'allowMultiple' (default false, exactly one winner). This enhances the agent's understanding of how parameters affect the user experience.

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: 'Opens the Picsart Asset Review board: a side-by-side grid of candidate assets' and immediately distinguishes it from sibling tools like picsart_generate (which creates assets) and other review tools (e.g., picsart_scene_review, picsart_video_review). It clearly states the tool's function as a comparison grid for user feedback.

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

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

Explicit guidelines are provided: 'Call this right after generating SEVERAL candidate stills for one purpose' and 'Typical flow: run picsart_generate two to four times... then pass every resulting URL here'. It also specifies URL constraints ('Pass Picsart-hosted https URLs only') and outlines the expected action after receiving the result ('read it and act on it'). This gives clear when-to-use and how-to-use instructions.

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

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

The description goes well beyond annotations by detailing read-only behavior ('spends no credits and works without authentication'), return value ('normalised passport payload'), constraints ('Pass Picsart-hosted https URLs only'), and locking condition ('treat lock as valid only when the stress-test has no failures'). Annotations already mark readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description adds critical operational context without contradiction.

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

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

The description is relatively long but well-structured, front-loading the primary action and then systematically covering usage guidelines, specific instructions, constraints, and return information. Every sentence appears necessary given the tool's complexity (10 parameters, nested objects, output schema). It is appropriately sized but could be slightly tighter 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?

Given the tool's high complexity (10 parameters, nested objects, output schema, specific constraints), the description covers all essential aspects: when to call, how edits work, locking prerequisites, URL restrictions, return format, and cost/authentication status. With an output schema present and schema coverage at 90%, the description is complete enough for an agent to use the tool correctly without additional clarification.

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

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

Schema description coverage is 90%, so baseline is 3. The description adds some semantic value, such as explaining that descriptor edits are surgical ('Apply descriptor edits to the named line only') and the URL constraint, but it does not elaborate on most parameters beyond what the schema already provides. The added value is moderate but not substantial enough to raise the score above baseline.

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

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

The description clearly states the tool opens the Picsart Asset Sheet for review and locking of film assets, distinguishing it from chat-based presentation by noting 'never paste a descriptor at the user in chat; this board is how an asset is shown to a person.' It specifies the resource (asset sheet) and the action (opens for surgical editing and locking), with explicit context for character, location, or prop sheets.

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 whenever a character, location, or prop sheet needs review or locking.' It also provides a clear negative guideline ('never paste a descriptor at the user in chat') but does not contrast directly with sibling tools like picsart_asset_review or picsart_save_asset. The guidance is clear but could be more specific about when not to use it versus alternatives.

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

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

Annotations indicate destructiveHint=true and readOnlyHint=false, but the description goes far beyond that by disclosing credit expenditure, required Authorization header, automatic model selection (recraftv3-replace-bg vs legacy), output structure, and the absence of resource_link blocks. It provides rich behavioral detail that 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?

The description is lengthy but every section serves a purpose: purpose, guidance, parameter details, output explanation, and warnings. It is front-loaded with the core function, then elaborates. Slight redundancy with the schema's required fields, but overall well-structured and dense with useful information.

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

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

Given the tool's complexity and the presence of many sibling tools, the description is remarkably complete. It covers return format, model behavior, credits, auth, and exclusions. With an output schema present, it appropriately doesn't repeat all return fields but explains key nuances like the `id` semantic and `metadata` tags.

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%, giving baseline 3, but the description adds substantial meaning: image must be a publicly accessible URL (not local path), prompt describes the new background, and the model param lets you override the auto-picked newest model. It also includes a concrete example mapping parameter values, enriching 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+resource statement: 'Replaces the background of an image with a new scene described by a prompt, keeping the foreground subject intact.' This clearly differentiates from sibling tools like picsart_remove_bg, picsart_enhance, and picsart_generate. The purpose is unmistakable.

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

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

The description explicitly states when to use the tool ('Use this when the user wants to "change the background to X"...') and provides a detailed list of when NOT to use it, naming exact alternatives ('use picsart_remove_bg', 'use picsart_enhance', etc.). It also mentions no need to call picsart_list_models first, adding practical usage context.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by explaining the returned fields in detail, noting the need for Authorization header, and clarifying that it takes no input. No contradictions with annotations.

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

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

The description is thorough but slightly long. It is front-loaded with the main purpose and then breaks down the fields. Every sentence is meaningful, but some technical details could be condensed slightly. Still, it is well-structured and easy 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?

Given no parameters, a complete output schema, and rich annotations, the description leaves no gaps. It explains the meaning of each field, when to use the tool, and the authentication requirement. It is fully complete for an agent to select and invoke the tool correctly.

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

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

There are zero parameters, so the description naturally adds no parameter-level detail. With 0 parameters, the baseline is 4, and the description adequately compensates by explaining the return fields and usage context.

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

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

The description clearly states it returns the Picsart credit balance and provides a detailed breakdown of fields (balance, resettable, accumulative, etc.). It also distinguishes from sibling tools like picsart_preflight by noting it should not be used for cost estimation, making its purpose precise and unique.

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

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

Explicitly tells when to use: before expensive operations to warn the user when balance is low, or after a 402 from picsart_generate. Also states when NOT to use it (for cost estimation) and points to the alternative tool (picsart_preflight). This provides clear context and exclusions.

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

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

The description discloses that this is a permanent deletion ('permanently removes the asset's subfolder'), specifies what gets deleted (portrait, turnaround, voice sample), mentions server-side scope checking, and states that the operation writes to Picsart Drive. It also notes the required authorization format. Annotations already say destructiveHint=true and readOnlyHint=false, so the description adds rich behavioral context beyond the annotations.

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

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

The description is front-loaded with the key information (INTERNAL, do not call directly) and provides all necessary details in a few well-structured sentences. It could be slightly more concise by removing the parenthetical 'and the portrait, turnaround, and voice sample inside it', but overall it's efficient.

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

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

Given the tool is a single-parameter destructive action with a simple output schema, the description is complete. It covers purpose, limitations, prerequisites, and behavior. It could include a mention that the output schema shows return format ('deleted, assetId, message'), but that's already provided. The description leaves little ambiguity for an AI agent.

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

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

The input schema already provides full parameter documentation (100% coverage), so the baseline is 3. The description adds value by explaining that assetId is 'a Drive folder uid that only the widget has' and that a wrong id is rejected by scope checks, which provides contextual meaning beyond the schema's description.

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

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

The description clearly states this tool is for deleting an asset from the library, invoked by the Picsart Asset Sheet widget. It specifies the verb ('delete'), the resource ('asset'), and the context ('from their library'), distinguishing it well from siblings like picsart_list_assets or picsart_save_asset.

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

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

The description explicitly says 'Do NOT call this directly from chat' and explains why (assetId is a Drive folder uid from the widget). It gives a clear alternative: ask the user to open the library via picsart_list_assets and delete from there. This provides both when-to-use and when-not-to-use guidance.

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

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

Annotations declare destructiveHint: true and readOnlyHint: false, but the description adds significant behavioral context beyond that: soft-deletes vs. permanent, authentication forwarding (user-id header, no bearer token), and side-effect differences (upload skips re-list to avoid panel reopening). The only minor gap is lack of explicit rate limit or quota info, but overall transparency is strong.

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

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

The description is well-structured: it opens with the tool's purpose, then uses a clear list for each action with consistent formatting. Every sentence adds value, covering action syntax, parameter options, behavioral notes, and a final authentication detail. No redundancy or filler—succinct yet comprehensive for a 6-action, 16-parameter tool.

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

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

Given the tool's complexity (16 parameters, 6 actions, output schema present), the description addresses all major aspects: action selection, parameter usage, return behavior, authentication, and integration hints (e.g., url for picsart_generate). Annotations already provide readOnly/destructive hints, and output schema is separate, so the description adequately rounds out the context.

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

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

Schema description coverage is only 25%, but the description compensates by explaining the role of key parameters per action (e.g., 'folderUid' for parent, 'file' vs 'url' + 'name' for upload, 'permanent' for delete). It adds context like 'flat' mode behavior and 'result.url' output, though some parameters (e.g., 'description', 'targetFolderUid') are only briefly mentioned. This goes well beyond the bare schema.

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

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

The description clearly defines 'picsart_drive' as a single entry point for the authenticated user's Drive, handling six distinct actions (list, create_folder, upload, move, delete, update). Each action is described with specific verbs and resources, effectively distinguishing the tool from siblings like 'picsart_list_assets' or 'picsart_media_upload', which target different resource types or workflows.

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 guidance on when to use each action, including syntax, optional parameters, and behavioral nuances (e.g., 'folderUid omitted = Drive root', 'flat: true' for flat listing). It also clarifies behavior for upload vs. other actions regarding re-listing, and notes that upload returns 'result.url' for use with 'picsart_generate', directly aiding tool selection among siblings.

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

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

The description adds substantial behavioral context beyond annotations: it spends credits, requires Authorization Bearer token, auto-picks the newest enabled model, returns a specific JSON structure with no duplicate resource_link blocks, and explains id and metadata semantics. Annotations already indicate destructive and non-read-only, but the description enriches this with actionable details without contradicting them.

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

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

The description is long but front-loaded with the core purpose, then usage triggers, exclusions, parameters, example, and output format. Every sentence adds distinct value. Slight length is justified by the tool's complexity, but it could be trimmed slightly by omitting the full output structure since an output schema exists.

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

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

For a tool with 3 parameters, full schema coverage, annotations, and an output schema, the description is remarkably complete: it covers triggers, non-use cases, authentication, cost, model selection, input constraints, output shape, and special display behavior. No critical context 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 already covers 100% of parameters, but description adds crucial semantics: image must be a publicly-accessible URL not a local file path, model is optional to pin a specific model, scaleFactor examples (2, 4), and a concrete usage example. This goes beyond the schema's terse descriptions.

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

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

The description opens with a specific verb and resource: "Upscales and enhances an image — sharpens edges, denoises, and raises resolution." It clearly distinguishes from siblings by naming alternative tools for background removal, background replacement, vectorization, and generation in the 'Do NOT use' section.

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

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

Explicitly states when to use: "Use this when the user asks to 'upscale', 'enhance', 'make it higher resolution', 'sharpen', 'clean up this photo', or 'make this 4k'." It also provides explicit exclusions with alternative tool names (picsart_remove_bg, picsart_change_bg, picsart_vectorize, picsart_generate), giving the agent clear decision criteria.

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

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

The description fully discloses behavioral traits beyond annotations. It explains the read-only nature explicitly ('Read-only; spends no credits and works without authentication'), which aligns with the readOnlyHint annotation. It details the internal behavior (compiles client-side style prefix, returns JSON message), how the return value should be used ('Store the returned stylePrefix verbatim; never reword it'), and the idempotent nature implied by 'Call it once... and again with `current`...' (consistent with idempotentHint). No contradictions with annotations.

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

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

The description is front-loaded with the core purpose and quickly lists the console's categories. It then adds critical usage behavior, parameter guidance, and a special note on the 'era' category. While every sentence is valuable, the description is somewhat long (approximately 150 words) and could be tightened further, e.g., 'The widget compiles the picks client-side...' could be more direct. Still, it is well-structured and dense with actionable information.

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

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

Given the complexity of this tool (5 parameters, nested objects, a revision parameter, inference requirements), the description is remarkably complete. There is an output schema, so it need not explain return format. The description covers all critical aspects: purpose, usage timing, prerequisites, parameter semantics, behavioral notes, read-only nature, and post-call data handling. No gaps are evident for the agent to successfully invoke this tool in a correct workflow.

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 100% coverage, so the baseline is 3. However, the description adds immense value beyond the schema. It explains the 'suggested' parameter's purpose in detail (why each category, must be pre-filled), the 'current' parameter's role in revision workflows, and the 'paletteHint' parameter's display behavior ('shown beside ... as a hint, not applied automatically'). It also gives semantic context for 'era' ('look of the IMAGE (film-stock decade), not the story's period'), which is far more than the schema's 'Preset ids per category' suggests.

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 this tool opens the Picsart Film Setup console, a visual preset picker for genre, era, camera/film stock, lens character, texture, tempo, and palette. It distinguishes itself from siblings like picsart_grade_console (color grading) or picsart_shot_designer (shot composition) by focusing on establishing a film's visual world style prefix. The verb 'Opens' and the specific resource 'Picsart Film Setup console' are precise.

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 guidance on when to call this tool ('once per visual world at the visual-bible lock'), when to revise ('again with current when the user wants to revise a look'), and crucial prerequisites ('Never open the console empty when the material has answers'). It tells the agent to infer categories from script, logline, or moodboard and pass them in 'suggested' with a 'why'. This clearly distinguishes this tool's usage from other setup or editing tools in the sibling list.

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

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

Annotations declare readOnlyHint and destructiveHint false. The description adds value by stating 'Read-only; spends no credits and works without authentication', which expands on the annotations. It also clarifies that user decisions 'come back as a JSON message in the conversation' and that the tool 'Returns the normalised pipeline payload'. The rule 'a hole in the matrix is a stop' further explains behavioral implications. 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 dense but every sentence contributes value. It front-loads the purpose ('Opens the Picsart Film Tracker'), then covers visual elements, usage conditions, parameter instructions, and return value. It could be slightly more structured (e.g., bullet points) but remains clear and efficient for a complex tool.

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

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

Given the tool's complexity (5 parameters with nested objects, output schema exists), the description covers purpose, when to use, parameter guidance, behavioral traits (read-only, no auth, no credits), and how to handle results. The output schema exists so return value details are not needed, but the description mentions the return type. The matrix rule and override debt concept add important contextual completeness.

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

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

Schema description coverage is 100%, so each parameter already has a description. The description adds usage semantics beyond the schema: it instructs to 'Pass all 11 stages every time' for stages, and 'pass the matrix during asset and generation phases' for the matrix parameter. It also explains the significance of matrix holes. While not deeply enriching every parameter, it provides phase-specific context that improves correct usage.

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 'Opens the Picsart Film Tracker: the 11-stage film production pipeline as a living map' and details what it shows (stage chips, gate status, checklists, matrix). This specific verb+resource combination distinguishes it from sibling tools like picsart_film_setup or picsart_generate. The purpose is unambiguous and well-differentiated.

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 enumerates when to call the tool: 'when opening a film session, when judging a gate, and whenever the matrix changes'. It also gives parameter-specific guidance: 'Pass all 11 stages every time' and 'pass the matrix during asset and generation phases'. It instructs the agent on how to handle results: 'Record a confirmed gate in the film state, and record an override verbatim with its reason'. This provides comprehensive usage context.

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

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

Despite the annotations already marking `destructiveHint: true` (spends credits) and `readOnlyHint: false`, the description adds substantial behavioral context: it clarifies that the tool spends credits, writes to Picsart Drive when enabled, that video models default to async and require polling via `picsart_job_status`, and that the call will reject unsupported params before charging. It also warns not to re-submit a video generation that seems to hang, a critical transparency detail.

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 quite long and comprehensive, but every sentence adds important context or guidance. However, it could be more front-loaded; the critical use-case guidance and examples are present, but the return structure details and async polling explanation could be condensed or structured as bullet points. At 500+ words, it is verbose though not wasteful.

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

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

Given the tool's high complexity (16 parameters, 2 required, nested objects, output schema exists, rich sibling set), the description is remarkably complete. It covers return format, async behavior, polling, credit spending, Drive integration, authentication, and provides both image and video examples. The output schema exists, but the description still explains the top-level keys and special cases (text models, video models).

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

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

With 100% schema description coverage, the description adds moderate value beyond the schema. It groups parameters as 'required inputs' and 'model-dependent optional inputs', provides two concrete examples with different model IDs, and explains special fields like `extra` (free-form record for model-specific params). It does not explain every parameter's format or range beyond what the schema provides, but the examples and grouping significantly aid 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 'runs any Picsart AI model end-to-end' and specifies the resources it produces: 'image, video, audio, or text result'. It differentiates this tool from many siblings by explicitly listing tools like `picsart_remove_bg`, `picsart_change_bg`, `picsart_enhance`, and `picsart_vectorize` that should not be used for their dedicated 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?

The description provides extensive when-to-use and when-not-to-use guidance. It instructs to skip calling `picsart_list_models` if you already have a model id, and alternatively to use `picsart_model_params` or `picsart_preflight` for validation. It explicitly warns not to use this tool for editing operations with dedicated tools, and not to use it for validation, cost quoting, or catalog browsing.

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

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

Annotations declare readOnlyHint and idempotentHint, but the description adds critical context: 'The widget performs no charged call itself', explains that 'preview' verdict triggers contact sheet (charged per frame) and 'apply' triggers apply_look, and notes it works without authentication. No contradictions with annotations.

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

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

The description is packed with essential workflow information, but it is somewhat long and could be more structured (e.g., separating prerequisites, steps, and return details). However, every sentence adds value, and it front-loads the core purpose. Minor loss for density over 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?

Given the tool's complexity (8 parameters, nested objects, workflow dependencies, and an output schema), the description covers prerequisites, invocation order, verdict handling, and result payload. The output schema exists, so return value details are not needed in the description. Fully sufficient for an AI agent.

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

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

Schema description coverage is 100%, so baseline is 3. However, the description adds significant value by explaining the workflow: why looks must come from live calls, how suggested/current interact, and why scope should be called per-scene then film. This exceeds what the schema alone provides.

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

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

The description explicitly states 'Opens the Picsart Grade Console: colour finishing for a picture-locked cut' and details what the console includes (look presets and sliders). It distinguishes from siblings by mentioning related tools like picsart_media_resolve_looks, picsart_media_contact_sheet, and picsart_media_apply_look, making its unique purpose 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?

Provides explicit guidance on when and how to use the tool: must resolve looks via picsart_media_resolve_looks first, never use remembered look lists, pass a suggested look with a why line, call with scope scene id before film scope, and outlines consequences for 'preview' vs 'apply' verdicts. This clearly differentiates from alternatives.

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

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

The description adds behavioral context beyond annotations, detailing the status objects (ACCEPTED, IN_PROGRESS with progress, COMPLETED with media, or error for FAILED/CANCELED), polling behavior, and the required Authorization header. Annotations only indicate readOnlyHint, etc., so this adds significant value.

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 5 sentences, each earning its place: core purpose, usage context, return types, and authentication. It is well-structured and front-loaded.

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

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

Given the tool's complexity (4 params, nested object, output schema exists), the description covers polling behavior, return types, relationships to other tools, and auth. It is complete for an agent to use correctly.

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

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

Schema coverage is 100% with descriptions, but the description adds usage guidance such as 'pass false when the caller persists the result itself' for saveToDrive, and explains that prompt is echoed into metadata. This provides context beyond the schema, warranting a score above baseline.

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

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

The description clearly states it checks a generation job started by picsart_generate with async: true, specifying the resource (generation job) and the context (async polling). It distinguishes itself from siblings by noting that assistants normally use synchronous calls and don't need this tool.

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

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

The description explicitly states when to use (widgets polling async jobs) and when not to (assistants using synchronous picsart_generate). It also mentions the return payload is the same as picsart_generate when complete, providing clear guidance on alternatives.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds value by stating it is 'Read-only; spends no credits' and specifies authentication needs ('Requires Authorization: Bearer <picsart_token>'). It also discloses internal behavior: reading a Drive folder, pairing files, and parsing manifests. No contradictions with annotations.

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

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

The description is 4-5 sentences, front-loaded with the main purpose. Each sentence serves a distinct role: purpose, internal behavior, usage guidance, behavioral summary, and return content. No redundant or extraneous information. Highly efficient.

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

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

Given the tool's simplicity (no parameters, has output schema), the description covers all necessary aspects: purpose, when to use, behavioral traits (read-only, no credits, auth), and what it returns ('widget config alongside {items, total}'). The output schema handles return details, so no further explanation is needed. Complete for an agent to decide and invoke correctly.

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

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

The tool has zero parameters and the input schema is empty. Schema description coverage is 100% (trivially). The description confirms 'Takes no input', which is the core semantic value. According to guidelines, 0 parameters earns a baseline of 4, and the description meets that without adding unnecessary detail.

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

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

The description explicitly states the verb 'Lists' and the resource 'user's saved Picsart film assets.' It details the reading of the 'Film Assets' Drive folder, pairing of portrait and turnaround files, and parsing of asset manifests. It also provides concrete example use cases ('show my film assets', 'open the asset library') that clearly distinguish it from siblings like `picsart_asset_sheet`.

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

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

The description tells the agent exactly when to invoke this tool: 'when the user wants to see the assets they built earlier, pick one to reuse, or manage them.' It explicitly excludes creation/editing by stating 'Do NOT use it to create or edit an asset (use `picsart_asset_sheet`)'. This provides unambiguous guidance on when to use it and when not to.

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 (readOnlyHint, idempotentHint, destructiveHint), the description discloses the tool renders a UI widget ('renders the Picsart Studio model-picker widget'), the fact it is read-only and costs no credits ('spends no credits and works without authentication'), and the truncation behavior in the return payload ('truncated is true when more matched than were returned'). This adds significant behavioral context not captured by annotations.

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

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

The description is long but well-organized: purpose first, then usage, then parameters, then inputType legend, example, and return shape. Every sentence contributes unique information, though some parts (e.g., the detailed inputType codes) could arguably be condensed. Still, for a tool with 8 optional filters and cross-tool distinctions, the thoroughness is justified.

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

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

Given the tool has 8 parameters, a UI side-effect, and strong sibling differentiation, the description covers all necessary aspects: what it renders, how to filter, what the input codes mean, an example, and the truncation behavior. The output schema exists, so return values need no further explanation. The description is fully adequate for selecting and invoking 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?

Although schema coverage is 100%, the description adds substantial meaning to parameters: it decodes the cryptic inputType codes (e.g., 't2v (text→video)'), explains the boolean filters in terms of model categories (acceptsImage → i2i, i2v, i2t), and provides a concrete example call. This goes well beyond the schema descriptions.

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

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

The description opens with a specific verb+resource+scope: 'Lists Picsart AI models across ALL modes' and explicitly distinguishes itself from siblings by naming alternatives like picsart_model_params, picsart_preflight, and picsart_model_catalog. This clearly identifies what the tool does and how it differs from related 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 states precisely when to use the tool ('when the user wants to SEE the available models or pick one themselves... for cross-mode searches') and when not to use it, with explicit alternative tools for each case. It also explains how to narrow to a single mode using the `mode` filter, providing a clear decision framework.

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, but the description adds substantial behavioral context: re-applying an effect replaces it in effects[] (explaining what idempotent means here), validation behavior with clear errors for unknown ids/params/ranges, and purity (no server-side state). This far exceeds the annotation baseline.

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

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

Every sentence in the description contributes meaningful information: purpose, return behavior, idempotency, validation, discoverability, and purity. There is no fluff, and the first sentence front-loads the core action. Dense but highly efficient.

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

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

For a 4-param tool with nested objects and no output schema, the description covers return value (updated scene with effects[]), error cases (unknown id/param, out-of-range), idempotency, purity, and how to discover valid values. This gives an agent all necessary context to invoke the tool correctly.

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

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

Schema coverage is 100% for all four parameters, but the description adds crucial semantics: omitted params get catalog defaults, params are validated by kind and numeric range, and effect ids/param shapes are discoverable via get_capabilities. This enriches the bare schema descriptions with actionable information.

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 ('Apply a named effect') to a specific resource ('a visual layer in an MP Scene') with concrete examples (gaussian_blur, drop_shadow, stroke). It clearly distinguishes from sibling tools like picsart_media_apply_look and picsart_media_apply_motion_preset by focusing on named effects and their parameter tuning.

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

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

The description implies usage context by explaining the effect application process, idempotent replacement, and discoverability via get_capabilities. It doesn't explicitly name alternative tools or when-not-to-use scenarios, but the context is clear enough for an agent to select this tool for named effect 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?

Despite readOnlyHint/idempotentHint annotations, the description adds crucial behavioral context: reference mode appends to looks[] and does NOT bake, expand eagerly bakes, and the pure functional nature ('takes the full scene by value, returns a new scene'). It also discloses the limitation with layered effects. 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 longer and dense, but it is well-structured with labeled sections (TWO MODES, NOTE, Pure) and front-loads the main purpose. Every sentence contributes meaningful information; however, the density makes it slightly heavy for quick scanning.

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

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

Given the tool's complexity (5 params, nested objects, no output schema), the description covers the essential aspects: modes, baking behavior, discoverability, purity, and limitations. It states the return value ('returns a new scene') even without an output schema. It does not discuss error conditions, but remains sufficient for a tool of this scope.

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 already documents all 5 params with 100% coverage, but the description enriches semantics: explains mode enum values, notes that params have catalog defaults and can be omitted, and clarifies layerId targets media or scene_ref. This goes beyond the schema's standalone text.

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

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

The opening sentence states a specific verb+resource ('Apply a composite look ... to a media OR scene_ref layer') and includes concrete examples (vintage_bw, light_leak). It clearly distinguishes itself from sibling tools like apply_effect by explaining the isolated nested composition and referencing resolve_looks.

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

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

Explicitly describes two modes with clear use cases: reference (default, deferred, non-destructive) vs expand (eager bake). Provides a when-not condition (layers with effects/animations/mask/blendMode can't take a look) and points to get_capabilities for discoverable looks and resolve_looks as an alternative for baking.

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 (readOnlyHint, idempotentHint, etc.), the description explicitly states the tool is 'Pure'—takes the full scene by value, returns a new scene, no server-side state. It also discloses error behavior (preset_kind_mismatch) and describes how animations+effects are merged. This adds substantial behavioral 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 compact yet information-dense. It front-loads the main action and then covers return value, preset constraints, discovery method, and purity. Every sentence earns its place with no fluff or redundancy.

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

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

Given the tool's complexity (nested objects, no output schema, multiple apply-* siblings), the description is remarkably complete. It explains what the tool returns, how to discover presets, the error condition, and side-effect-free behavior. It references the capabilities tool for additional details, which is appropriate. No significant gaps remain.

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

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

The schema already covers all four parameters with descriptions (100% coverage), so the baseline is 3. The description adds value by explaining preset semantics (appliesTo kinds), error conditions, and that params are optional overrides. It also clarifies the scene is a full document, not a reference. This enriches the parameter meaning beyond the schema.

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

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

The description clearly states that the tool applies a named motion preset to a visual layer in an MP Scene, with specific verb ('apply'), resource ('motion preset'), and target ('visual layer'). It distinguishes itself from sibling 'apply_*' tools by focusing on motion presets and providing examples (glow_pulse, ken_burns, scale_pop). The return value (updated scene) is also stated.

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: the tool is for applying motion presets to layers, and it points to 'picsart_media_get_capabilities' for discovering available presets and parameter shapes. It also implies that presets have an 'appliesTo' constraint, warning about mismatches. However, it does not explicitly contrast this with sibling tools like 'apply_effect' or 'apply_look', so it lacks explicit when-not-to-use guidance.

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

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

The description details the exact behavior of each mode: reference produces a scene_ref that becomes a nested composition, bootstrap strips parameters and synthesizes assets, inline merges with id-prefixing and asset rewiring. It also confirms the operation is pure and returns a sceneRef or scene, adding value 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 relatively long (about 200 words) but every sentence conveys necessary information about modes, usage, and fallbacks. It could be slightly more concise with bullet points, but the dense content is justified for a tool with three distinct operational 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?

Despite lacking an output schema, the description clearly states the return type ('sceneRef or scene plus the applied parameter map'), describes mode-specific side effects, and explains when to use this tool versus quickstart. It also covers required prerequisites (describing template parameters) and edge cases like template resolution from registry.

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 all 9 parameters with descriptions (100% coverage), giving a baseline of 3. The description adds meaning by explaining which parameters apply to which mode (e.g., 'at' is inline-only, 'fit'/'trim'/'timeScale' are reference-only) and clarifying the default mode. This improves 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 opens with "Instantiate a scene template with the supplied parameter bindings," which is a specific verb+resource combination. It further clarifies the three modes (reference, bootstrap, inline) and contrasts with sibling tools like apply_effect, making it easy to distinguish.

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

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

Explicit guidance is given: use picsart_media_describe_scene_template first to learn parameters, and for common video jobs use picsart_media_quickstart with recipe:'concat_videos' instead. It also states when no scenes entry is needed for standard library templates, covering when-to-use and alternatives.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses the pure functional behavior: 'takes the full scene by value, returns a new scene; no server-side state.' It also specifies the exact mutation point (appended to content.animations[]) and the return type (updated scene), which are not implied by annotations alone.

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 five sentences long, with each sentence serving a distinct purpose: main action, return behavior, preset discovery, alternative approach, and purity guarantee. It is front-loaded with the key action and avoids any wasteful repetition.

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

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

Given the tool's moderate complexity (nested objects, no output schema) and rich annotations, the description thoroughly covers the essential information: what it does, how to find valid presets, what it returns, where changes occur, and when to use a different approach. No critical gaps that would prevent an agent from using 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 input schema provides 100% coverage with descriptions for all parameters, but the description adds extra semantics by clarifying that 'params' are optional preset overrides, the 'scene' parameter is the full scene passed by value, and providing examples for the 'preset' parameter. This goes beyond mere schema repetition.

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

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

The description clearly states the tool applies a named text-animation preset to a text layer in an MP Scene, with concrete examples like 'typewriter' and 'fade_in_chars'. It distinguishes itself from siblings like picsart_media_apply_motion_preset by focusing specifically on text animations and also mentions an alternative for custom shapes.

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 guidance: presets and their parameter shapes are discoverable via picsart_media_get_capabilities. It also explicitly states when not to use the tool—when custom animation shapes are needed, agents can write MpTextAnimation entries directly—thus giving a clear alternative.

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

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

Goes well beyond the annotations by disclosing auth is handled automatically, inline images are best-effort under a size/count budget, partially-inlined sheets are a success, and retrying re-charges the render. It also clarifies that at most 8 frames come back inline regardless of request count, adding crucial behavioral nuance.

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 well-organized, front-loading the purpose and then systematically covering modes, usage context, auth, failure semantics, and alternatives. While each sentence adds necessary information, the length could be trimmed slightly without losing value, 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?

Covers return format, charging behavior, inline vs url fallback, prerequisites (validate scene), scope, and exclusions. Despite having an output schema, the description still explains the inline vs url response and success semantics, making it fully complete for an agent to invoke correctly.

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

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

Adds significant meaning beyond the schema: `times` yields exact thumbnails per requested time and is preferred, `frames` does evenly-spaced sampling with 1fps integer-second granularity, `times` overrides `frames`, and `resolution` defaults to width 480. This is far more than the schema provides.

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

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

Clearly states it renders a multi-frame overview of a scene as low-res jpeg thumbnails with inline images and a machine-readable frames JSON. It explicitly situates itself between a single full-res frame check and full export, distinguishing it from sibling tools like picsart_media_probe_media and picsart_media_query_layout.

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

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

Provides explicit guidance: prefer `times` for exact moments, use for eyeballing pacing/seams before export, and not as a metadata probe (use picsart_media_probe_media first). Also instructs to validate the scene first and names alternative tools for layout checks, giving clear when/when-not context.

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

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

Annotations already declare `readOnlyHint=true`, `idempotentHint=true`, and `destructiveHint=false`. The description adds valuable behavioral constraints beyond that: the URI scheme version restriction ('in v1; other schemes are deferred') and the exact return shape (`{ id?, uri, composition, parameters }`). This is more than baseline but not exhaustive (e.g., error behavior is not described).

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 dense with information: purpose, usage context, and return details. No filler or repetition. The key information is front-loaded in the first sentence.

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 describe tool with strong annotations, the description is very complete. It states what it does, when to use it (with an explicit sibling reference), what URI schemes are accepted, and what the response contains. There is no output schema, so the explicit return format `{ id?, uri, composition, parameters }` covers that gap.

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

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

The schema has 100% coverage with one parameter (`uri`) already described as 'Template URI, e.g. "mpscene://montage"'. The description adds further meaning by specifying the accepted scheme ('mpscene://<id>') and the version limitation ('in v1; other schemes are deferred'), which goes beyond the schema's basic example.

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: 'Describe a single MP Scene template by URI' and clearly states what it returns ('declared parameters... and composition dimensions'). It also distinguishes from the sibling tool by explicitly connecting to 'picsart_media_apply_scene_template'.

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

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

It gives explicit usage context: 'Use this before `picsart_media_apply_scene_template` so you know what to pass.' It also specifies URI scheme support ('Accepts `mpscene://<id>` URIs in v1; other schemes are deferred'), which tells the agent when the tool is applicable.

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

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

Goes well beyond annotations by disclosing that it does NOT fetch, only resolves in-memory mpscene:// refs, remote refs remain untouched, unresolvable behavior differs between bulk mode (left as-is) and single-layer mode (error), and the operation is one-level deep. Ends with 'Pure', confirming no side effects. This richly supplements the readOnlyHint and idempotentHint.

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

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

The description is lengthy but dense and front-loaded with the core action. Every sentence provides meaningful behavioral detail, including sync/async, remote vs local refs, and error cases. Slightly verbose with some technical asides (e.g., 'prefixed by the ref layer's id'), but no wasted content warrants 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 complexity of handling scene_refs, the description fully covers operation semantics, limitations (one level, only in-memory), remote ref handling, error behavior, and practical timing advice. With no output schema, the description still leaves the agent well-informed about what happens and when to call.

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 have descriptions in the schema. The tool description adds no new parameter-level syntax or meaning beyond what the schema already provides; it mostly explains behavior that depends on the parameters rather than their individual semantics. Meets the baseline for high schema coverage.

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 'DETACH a scene_ref into editable layers' and clearly explains the resource and action. It also distinguishes itself from siblings by explicitly framing this as the inverse of the by-reference model, which differentiates it from related tools like picsart_media_apply_scene_template.

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

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

Explicit usage guidance is provided: 'I referenced a template, now bake this instance to customize it beyond its parameters' gives a concrete use case. It also tells when NOT to use it by explaining remote refs are left as-is and recommending detach after a translate/preview/query has inlined them, and mentions alternative automatic resolution at translate/render/query-layout.

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 the tool as mutating (readOnlyHint: false) and destructive (destructiveHint: true). The description adds valuable behavioral context: 'Auth is handled by the platform automatically — no token setup needed,' no local renderer, and that it performs the 'ACTUAL render' via server-side dispatch. It doesn't detail potential destructive effects, but the annotations already cover that baseline, and the description adds context beyond them.

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

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

The description is dense with valuable information, but every sentence earns its place: purpose, format differentiation, auth note, and workflow guidance. It's not overly verbose, though it could be slightly tightened by removing the 'no local renderer' redundancy with 'server-side' mentioned earlier. Overall well-structured and informative.

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

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

Given the tool's complexity (9 params, nested objects, output schema present), the description is complete: it explains the output (URLs), differentiates major modes, provides prerequisites and alternatives, and mentions auth. It doesn't need to detail return values since an output schema exists. The description leaves no major gaps for an agent to invoke the tool correctly.

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

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

Schema coverage is 100% with rich param descriptions, giving a strong baseline. The description adds meaning by mapping `format:"video"` / `format:"image"` to the `mediaType` parameter and explaining the default behavior. Minor confusion arises because the description uses 'format' while the schema field is 'mediaType,' but it still clarifies the output type 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 tool's function: 'Render a fully-authored MP Scene to a final file via the server-side `media-platform/v3/export` workflow, returning the output URL(s).' It specifies output formats and explicitly differentiates from a 'pure scene→scene deck compiler,' which helps distinguish it from sibling tools like `picsart_media_video_render`.

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

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

The description provides explicit when-to-use guidance: instructs to validate the scene first (`picsart_media_validate_scene`), check a frame (`picsart_media_contact_sheet`), and points users to `picsart_media_quickstart` if they don't yet have a scene. It also clarifies when the tool is not the right choice, e.g., avoiding reverse-engineering from schema. This goes beyond basic usage to offer a clear workflow.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the size implications (~135KB full, ~62KB looks, ~8KB looksCompact), the result-cap overflow risk, the index-only default, and an explicit 'dependency-free; safe to cache' note. This enhances transparency without contradicting annotations.

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

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

The description is long but every sentence earns its place: purpose, usage timing, parameter behavior, a critical size warning, a key list, and cacheability. It is front-loaded with the most important information. Slightly verbose, but the density is justified by the complexity of the operation and the need to prevent invocation errors.

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

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

With no output schema, the description carries the full burden of explaining return behavior. It explicitly states the default return (section index names only), lists top-level keys (supports, limits, engine, featureMatrix) and all sub-keys, and warns about response sizes. This is complete enough for an agent to know what to expect and how to avoid overflow, fulfilling all necessary contextual information.

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

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

Schema description coverage is 100% and already explains the `sections` parameter well. The description adds further meaning by enumerating the exact top-level and sub-keys available (effects, transitions, looksCompact, etc.) and providing usage patterns like PREFER granular sub-keys. This goes beyond the schema's summary and helps the agent select valid sections, though the schema already carried much of the burden.

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

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

The description opens with a specific verb+resource: 'Returns the MP SDK tool layer's capabilities' and enumerates the exact content (layer content kinds, animatable properties, effect ids, transition ids, operational limits). It distinguishes itself from siblings by explicitly positioning it as 'Call this first when planning a composition,' making its role 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?

Explicitly instructs when to use: 'Call this first when planning a composition so subsequent calls stay within supported bounds.' It also provides detailed how-to guidance on section selection, including the preference for granular sub-keys and the specific warning to use 'looksCompact' before 'looks' to avoid overflow. This is actionable and distinguishes usage patterns.

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 read-only and idempotent hints, but the description adds meaningful behavior: the schema is 'authoritative' and any document validating against it is accepted. It also discloses the ~66 KB size and that name returns a single definition with internal $refs pointing to #/definitions, which is not visible in annotations or schema.

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

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

Three sentences, each earning its place: purpose, usage guidance with sibling mentions, and parameter details. Front-loaded with the core action, no redundancy.

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

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

For a read-only schema getter with one optional parameter, the description covers purpose, when to use, behavior of the returned schema, and parameter semantics. The absence of an output schema is compensated by the description explaining what it returns. This is complete for the tool's simplicity.

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 describes the 'name' parameter well, so baseline is 3. The description adds value by explaining the size difference (~66 KB full schema vs single definition) and the internal $ref behavior, which helps the agent decide whether to pass 'name'.

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: 'Returns the JSON Schema for an MP Scene document.' It clearly distinguishes this tool from siblings like picsart_media_validate_scene and picsart_media_contact_sheet by framing it as a schema-retrieval utility.

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

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

Explicitly states when to use: 'Use this to construct valid scenes from scratch or to remind yourself... before calling picsart_media_validate_scene or checking a frame with picsart_media_contact_sheet.' This names alternatives and provides workflow context.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds critical context: no system-font fallback, stable key, resolved URL, accepted_url_pattern, dependency-free, safe to cache. No contradiction.

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

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

Well-structured, front-loaded with purpose, then usage, then error context. Every sentence adds value.

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

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

For a simple zero-param tool, the description covers purpose, usage, output format, error behavior, and caching properties. Complete given no output schema.

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

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

Tool has zero parameters, so baseline 4 applies. The description mentions no parameter details, but none are needed.

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

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

Specific verb+resource: 'Returns the curated font catalog.' It clearly distinguishes from sibling tools as the font listing tool, 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?

Explicitly states 'Use this before authoring any text layer' and explains the consequence of not using it (unknown_font_family error). No direct alternatives exist, but context is clear.

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

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

Annotations already mark readOnly, idempotent, non-destructive. Description adds 'Pure: no inputs, no state', which reinforces no-side-effect behavior and adds a stateful claim beyond annotations. It also documents return payload shape.

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

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

Four short sentences, front-loaded with the core action. No filler; each sentence adds a distinct type of info: operation, data content, usage context, return/purity.

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 it's a zero-input enumeration tool, the description covers purpose, usage, return format, and behavioral guarantees. Sibling context confirms this sits next to describe/apply tools; the description explicitly places itself 'before' those.

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; schema is empty with 100% coverage. Baseline is 4 per rubric; description appropriately notes 'no inputs' and explains that discovery is by template attributes, not inputs.

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 'Enumerate the curated MP Scene template catalog' – a specific verb ('enumerate') and resource ('MP Scene template catalog'). It also distinguishes from siblings by noting use 'before describing or applying one', clearly differentiating from describe/apply tools.

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

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

Explicitly states when to use: 'Use this to discover templates by id/category/aspect before describing or applying one.' This provides timing relative to sibling operations, effectively giving usage guidance and alternatives.

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

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

Annotations provide readOnly, openWorld, idempotent, and non-destructive hints. The description adds substantial behavioral detail beyond these: it creates a new MP Scene with a grid layout, explains how scene_ref.fit is handled, notes that it carries the deck's scenes/assets, and describes default behavior for grid, size, and duration. No contradictions with annotations.

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

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

The description is dense but well-organized, front-loaded with the core purpose, then technical details, defaults, and final exclusions. Every sentence adds useful information without fluff or redundancy.

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

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

Given the tool's complexity, a rich input schema, and no output schema, the description sufficiently covers the transformation process, defaults, constraints, and expected output. It also provides enough context for a user to decide whether to call this tool over siblings.

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

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

Input schema covers 100% of parameters with meaningful descriptions, so baseline is 3. The description adds value by emphasizing which parameters are overridable ('Override cols/gap/width/height/duration') and providing technical context about scene_ref.fit and board sizing, going slightly beyond the schema.

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

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

The description states a specific action: 'Compile a presentation DECK ... into an OVERVIEW / badges board' with a grid of shrunken thumbnails. This clearly distinguishes it from sibling tools, and it explicitly clarifies what it is NOT: 'NOT a capability index or a getting-started tool despite the 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?

The description gives clear usage context: it is for an 'existing deck scene you already authored' and is a 'Pure scene→scene' operation. It also explicitly names the alternative for capability queries: 'If you are looking for what can this server do ... call picsart_media_quickstart instead.'

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses critical behavioral traits: atomicity of the entire batch ('first failing op aborts the WHOLE batch'), non-mutation of the input scene ('input scene is never mutated'), internal validation via the picsart_media_validate_scene pipeline, and error structure ('typed error carrying code and opIndex'). It also clarifies which collections are id-less and how to handle them.

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

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

The description is long but every sentence delivers an operational rule or clarification. It is front-loaded with the purpose, then systematically covers verbs, addressing, path syntax, atomicity, validation, and edge cases. There is no fluff—each detail like 'replace is accepted as a first-class alias' or the id-less collection paragraph earns its place for a complex tool.

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

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

Given the tool's complexity and absence of an output schema, the description covers all necessary aspects: how to construct ops, how to address anchors vs root fields, path escaping, atomic failure semantics, internal validation and its implications, and handling of id-less collections. It even explains the interplay with picsart_media_validate_scene, making it self-sufficient for correct invocation.

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

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

While the schema covers the two parameters with basic descriptions, the description adds extensive meaning for the 'ops' parameter: verb semantics (set/remove/add), anchor types (layer/asset/audio/marker), path syntax with ~0/~1 escapes, and the requirement for a value carrying an id. For the 'scene' parameter, it clarifies it can be a URL. This far exceeds the schema's bare descriptions.

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

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

The description opens with a precise verb+resource: 'Apply a batch of incremental, ID-ANCHORED edit ops to an MP Scene and return the patched result'. It clearly distinguishes this tool from siblings by positioning it as 'the token-cheap alternative to re-emitting the entire scene on every edit' and enumerates three specific verbs (set/remove/add).

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 (token-cheap incremental edits) and when not to: 'do NOT call picsart_media_validate_scene again right after a successful patch; only validate once you've made further hand-edits outside this tool.' It also provides rules for addressing targets (anchor vs root index) and id-less collections, giving clear conditional 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 (readOnlyHint, idempotentHint, destructiveHint) already establish safety, but the description adds a wealth of behavioral context: SSRF-guarding, bounded ranged fetches, 'dimensions are never invented' for unrecognized containers, the semantics of missing durationSeconds (never 0 for real zero-length), and the stochastic annotation rationale ('a URL's content can change between calls'). This goes far 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 long but each paragraph serves a purpose: summary, usage, security, duration semantics, and best-effort extras. It is front-loaded with the core return fields and usage context. While some sentences could be tightened, the complexity of the tool (edge cases for duration, fragmented MP4, SSRF) justifies the length. It earns a 4 rather than a 5 due to slight redundancy in the stochastic explanation.

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

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

With no output schema, the description takes full responsibility for explaining return values, edge cases, and failure modes. It covers what is returned for recognized and unrecognized formats, how missing fields should be interpreted, security behavior, and cost-savings usage. This is a complete picture for an AI agent to decide when and how to invoke the 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 already has 100% coverage for the single 'url' parameter, including 'Public http(s) URL... SSRF-guarded ranged fetch, file is not downloaded'. The description does not add new parameter-level details beyond what the schema states; it reinforces the same constraints but doesn't introduce novel semantics, so the baseline of 3 is appropriate.

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

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

The description opens with a precise verb ('Returns') and resource ('remote media URL's metadata'), listing specific fields ('kind', 'width'/'height', 'durationSeconds', 'contentType', 'bytes'). It explicitly contrasts with downloading, making the tool's purpose unmistakable and distinct from siblings like picsart_media_export or picsart_media_validate_scene.

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

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

The description provides explicit when-to-use guidance ('Use this BEFORE authoring a scene to size compositions, pick fit, set clip windows...') and when-not-to-use ('Skip this call if you already know the asset's exact width/height/duration from a prior tool result'). It also names alternatives ('instead of shelling out to curl/ffprobe or guessing'), covering both positive and negative usage cases.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds substantial behavioral context: coordinate unification across both engines, deterministic output, text-layer placeholder boxes, the need for `sceneContext` in multi-group V3 scenes, and the caveat that a clean layout does not guarantee renderability. No contradiction with annotations exists.

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

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

The description is long but well-structured: it front-loads the core purpose, then systematically details return fields, limitations, and caveats. Each section is necessary for a complex tool. Minor redundancy exists (e.g., 'Determinism is deterministic') and the repeated references to contact_sheet add a slight amount of extra length, but overall the length is justified.

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

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

Even without an output schema, the description previews the major return fields (`box`, `center`, `rotationDeg`, `zIndex`, `active/visible`, `onCanvas`, `timing`, `nesting`), explains prerequisites like `sceneContext` for multi-group V3, and details text-layer limitations and the `scope` caveat. It is exceptionally complete for a tool of this complexity.

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

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

Schema coverage is 100%, giving a baseline of 3. The description adds meaning beyond the schema by explaining that `engine` only changes the translation path while coordinates are unified, that `verbose` yields raw 4x4 matrices and chain details, and that `scene` can be a URL. This is valuable extra context, though the schema already documents types and requirements.

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: 'Resolves where every layer ACTUALLY LANDS in the root composition at a given time — without rendering pixels.' It clearly differentiates from sibling `picsart_media_contact_sheet` by emphasizing that it returns geometry rather than a rendered frame, making the 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 explicitly instructs when to use the tool: 'use it instead of (or before) checking a rendered frame (`picsart_media_contact_sheet`)' and when not to use it: 'GEOMETRY ONLY — this is NOT a render/export gate.' It also directs users to confirm renderability with `picsart_media_contact_sheet` / `picsart_media_export`, providing clear alternatives and exclusions.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds behavioral details: it returns sequences (not executing them) and that omitting recipe gives an index. No contradiction with annotations. Slightly less than perfect because it doesn't mention any potential limitations or response structure, but adequate.

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, each earning its place: first states purpose and timing, second gives parameter guidance. No fluff, front-loaded with the key instruction 'Call FIRST'.

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

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

For a simple tool with one optional parameter and no output schema, the description fully covers what the tool does, when to use it, how to invoke it, and what to expect in return. No gaps given the context signals.

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

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

Schema coverage is 100% with enum values. The description adds meaning by explaining the two modes: omitting for the index or passing a value for step-by-step sequences. This clarifies usage beyond the schema's enum list.

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

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

The description clearly states the tool provides 'ready-to-run picsart_media_* tool-call sequences' for specific media tasks. It uses a specific verb ('Call FIRST') and resource ('how-to recipes'), and distinguishes itself from sibling tools that perform the actual tasks.

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

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

Explicitly says 'Call FIRST when the user asks how to accomplish a media task' and lists example tasks. It also tells when to omit the parameter ('Omit `recipe` for the index'), providing clear usage context and alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds critical behavioral traits beyond those: it is pure (takes full scene by value, returns new scene), idempotent even without looks, and bakes preset logic to eliminate look-catalog dependency. No contradictions with annotations.

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

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

The description is dense but efficient—four sentences each carrying essential information: action/result, sibling context, usage directive, and idempotence/purity. No filler or repetition of structured annotations.

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

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

For a 1-parameter tool with no output schema and strong annotations, the description covers what, why, when, and edge-case behavior. It explains the return value (self-contained scene) and what it means for rendering dependencies, making it adequately complete for the tool's complexity.

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

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

Schema coverage is 100% and the parameter description already explains the scene role. The description adds semantics beyond the schema by clarifying the exact transformation (expand by-reference looks into concrete nested composition), purity ('takes the full scene by value'), and the no-op case when no looks[] are present.

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 ('Expand') and resource ('by-reference look in an MP Scene'), clearly stating the transformation into a self-contained scene. It also distinguishes itself from sibling tools by framing it as the explicit, on-demand counterpart to internal just-in-time resolution in tools like picsart_media_translate_scene.

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

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

The description explicitly says 'Use it to flatten...' and provides concrete use cases (hand off, archive, edit expanded layers), while contrasting with internal resolution in siblings. It lacks an explicit 'when not to use' but the implied alternative guidance is strong.

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

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

Annotation contradiction: The description explicitly says 'WRITE it to a content-addressed file' and 'it goes to disk', which is a write operation, yet the annotations declare readOnlyHint: true. This directly contradicts the read-only hint. While the description discloses other behaviors (caching, determinism, no re-validation), the contradiction forces a score of 1.

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 somewhat long but every sentence provides necessary information: the action, the reason for writing to disk, engine specifics, output file location, and determinism. It is front-loaded with the core purpose and structured logically. It could be slightly trimmed, but the length is justified given the tool's complexity.

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

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

With no output schema, the description fully covers return values (`{ path, cached, summary }`) and explains the external side effects (file path, caching). It also addresses edge cases like token overflow, engine-specific outputs, and the need to validate first. Given the tool's complexity, the description is remarkably complete.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema. It explains the `engine` parameter's effect in detail (`v3` → Replay file structure, `jet` → Jet project format), the default value, and the `scene` parameter's URL option. This goes well beyond the bare schema descriptions, making the parameters fully understandable.

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

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

The description clearly states the tool's verb and resource: 'Translate an MP Scene document into an engine's project format, WRITE it to a content-addressed file, and return { path, cached, summary }.' It distinguishes this from sibling tools by emphasizing the translation/writing behavior and the specific output format, 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 provides clear context on when to use the tool and how to handle outputs: it explains that the file should be read when the full project is needed, and explicitly recommends validation first ('Validate the scene first; the translator does not re-validate'), which implies using the validation sibling tool. It doesn't name alternative tools directly but gives practical usage guidance.

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

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

Annotations already indicate readOnlyHint=true, but the description adds critical behavioral details beyond that: the upload happens in the user's browser directly to Picsart's CDN without passing through the tool, the two-turn handshake, and the fact that detected_files is a best-effort hint that never filters. These go well 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 relatively long but every sentence serves a purpose: purpose, usage, parameter details, and the handshake explanation. It is front-loaded with the core action. Could be slightly more concise, but it earns its length for the complexity involved.

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 two-turn handshake and user-interaction nature, the description is fully complete. It explains the asynchronous result flow, the role of each parameter, and the non-filtering behavior of detected_files. With a rich annotation set and output schema implied, nothing 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 meaningful extra context for detected_files (warning about hallucination and that it's a suggestion only) and known_urls (seeds pickable chips). This goes slightly beyond the schema's own descriptions, justifying a 4.

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

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

The description clearly states the tool 'Opens a drag-and-drop upload widget' to get a local media file into the conversation as a URL. The verb 'opens' and specific resource 'upload widget' distinguish it from sibling picsart tools, none of which handle local file upload directly.

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

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

Explicitly specifies when to call: 'whenever a user wants to use a local file with any picsart_media_* tool, or after a local-path argument was refused with a local_source_not_supported error.' Also notes the two-turn handshake, advising that results come on the next message. No alternative usage is needed; the context is fully covered.

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

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

Annotations already declare readOnly, idempotent, and non-destructive hints. The description adds meaningful behavioral details beyond that: it states the tool is pure, takes the full scene, and that results are only valid for the current scene state, advising to call again after edits. It also explains the diagnostic structure and validity condition, enriching the annotation context.

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

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

The description is three sentences with no filler. It front-loads the verb and resource, then provides concise, useful details about the output format and usage scenario. 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?

Given the tool's moderate complexity, the description covers the key aspects: what it validates, when to use, what the output looks like, how to interpret validity, and its pure behavior. With annotations already handling safety, no output schema exists but the diagnostic structure is described. This is complete.

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

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

The schema description already fully covers the single parameter ('The MP Scene document to validate, or an http(s):// URL to fetch it from'). The description adds the notion of passing the 'full scene' and mentions re-calling after edits, but this is more usage guidance than parameter semantics. At 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Validates') with an explicit resource ('an MP Scene document') and states the main output ('a list of structured diagnostics'). This clearly distinguishes it from sibling tools like picsart_media_patch_scene or picsart_media_export, which perform different 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 gives explicit guidance on when to use it: 'Use this whenever you've assembled or modified a scene, especially before rendering.' It does not mention alternatives or when not to use it, but given the tool's unique validation role among siblings, this is clear enough context.

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

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

The description adds significant context beyond annotations: it notes that the tool never renders, returns a code_url that must be rendered separately, the thumbnail is a url only and unverified until rendered, the tool costs 25 credits, and it writes new code from a brief every time (non-idempotent). It also mentions render duration limitations. Annotations already indicate destructiveHint=true, and this description is consistent.

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 the main action first, but it is somewhat long with multiple clauses and alternative listings. Each sentence adds value, but it could be slightly more concise without losing essential details. The front-loading is good.

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

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

Despite having no output schema, the description covers the return values (code_url, thumbnail_url), explains the thumbnail is a url only and not viewable inline, provides credits cost, differentiates from siblings, and gives usage guidelines. It is complete for the agent to understand the tool's behavior and integration.

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

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

Schema coverage is 100% so baseline is 3. The description adds extra meaning for the 'brief' parameter (self-contained, no conversation memory) and the 'duration' parameter (render cap limitation, may need trimming). This improves the agent's understanding 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 explicitly states 'Generate a NEW short motion-graphics video ... from a natural-language brief', providing a specific verb and resource. It distinguishes from sibling tools by noting that Scene tools cap at 1920x1920 and listing excluded use cases (template-based slideshows, montage, contact sheets, captions).

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?

Clear when-to-use guidance: 'use this for output above 1920x1920, since the picsart_media_* Scene tools cap at 1920x1920'. Also explicit when-not-to-use: 'NOT for template-based slideshows/decks ... montage/concat ... contact sheets ... captions burned over existing user media — those are all picsart_media_* Scene tools and are cheaper and deterministic'. Additionally, outlines the next step (call picsart_media_video_render).

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. Description adds cost per resolution (5-10 credits), duration caps (15s/10s), and a real-time warning (30s render ~32 min). This justifies the conservative cap and aligns with annotations. No contradiction.

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

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

Description is structured with clear sections: purpose, resolution options, cost, caps, scene composition note. It's front-loaded with the core purpose. Slightly verbose but every sentence adds necessary context.

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

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

Covers all essential aspects: input source, output format/max resolution, cost, duration caps with rationale, and guidance for scene integration. Output schema exists, so return values need not be described. Complete for a complex tool.

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

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

Schema coverage is 100%, baseline 3. Description adds meaning for duration_seconds: tells agent to copy metadata.duration from the source result and explains it's used for a pre-render safety check. For resolution, it clarifies defaults and scene composition implications.

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

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

Description clearly states the tool renders a code_url from video_create/revise to a final MP4 up to 3840x2160. It distinguishes from sibling tools like export by noting they cap at 1920x1920, so this tool handles higher resolutions.

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

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

Explicitly says to use for output above 1920x1920. Provides guidance when compositing into an MP Scene: use hd/full_hd because MP composition caps at 1920x1920. Also details cost and duration caps, helping the agent decide when to invoke.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds critical behavioral context: statelessness (no memory between calls), that it returns a new code_url but does not render (call picsart_media_video_render next), and the cost of 25 credits. No contradictions with annotations.

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

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

The description is a single paragraph of about 5 sentences, covering purpose, usage, behavior, parameter nuance, and cost. It is efficient with no wasted words, but could be slightly more structured (e.g., bullet points for the key rules). Still, it earns its length.

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

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

Given 4 parameters, no output schema, and annotations present, the description addresses purpose, usage alternatives, parameter behavior, statelessness, next step, and cost. It does not explicitly describe the return value format beyond 'new code_url', but that is sufficient for a revision tool that returns a code_url. The mention of 'same routing rule' is a bit vague but acceptable.

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% (all 4 parameters described). The description adds value beyond the schema by clarifying when to use the `error` parameter ('fix mode only'), emphasizing that `instruction` must be a full description because of statelessness, and reinforcing that `code_url` comes from a prior create/revise result. This contextual guidance helps the agent use parameters correctly.

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+resource ('Edit or fix an existing picsart_media_video_create/picsart_media_video_revise output') and explicitly distinguishes from sibling tools by naming the picsart_media_* Scene tools for alternative use cases. It also clarifies the tool's stateless nature and what it returns, making its role 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 provides explicit when-to-use guidance ('Use for output above 1920x1920...') and when-not-to-use ('for template slideshows... use the picsart_media_* Scene tools instead'). It also explains the conditional use of the `error` parameter (only for fixing a broken render) and the stateless requirement to describe the full change each call. This gives the agent clear decision-making rules.

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, destructiveHint=false, idempotentHint=true; description adds context by noting 'Read-only; spends no credits and works without authentication.' It also discloses return behavior: 'Returns `{ items, total, truncated }`' and explains `truncated` semantics, plus the token-saving `concise` mode. No contradictions.

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

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

Long but structured: purpose, usage vs sibling, parameter semantics, inputType code legend, return shape. Front-loaded with the key distinction. Every sentence earns its place; 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 tool has 8 optional params, an output schema, and rich annotations. The description is fully self-contained: it covers all params, return shape, pricing/credit behavior, authentication, and explicit exclusions. Sibling tools are referenced for complementary needs. Extremely complete.

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

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

Schema coverage is 100% but the description adds meaning beyond enums: explains `mode` values (e.g., 'text = LLM models that return generated text'), `provider` is 'case-insensitive substring', `inputType` is an 'exact-match escape hatch', and defines all 15 inputType codes. It also clarifies `concise` changes item shape. This goes well beyond schema.

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

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

Description opens with a specific verb+resource: 'Returns the Picsart AI model catalog as plain data — renders NO widget or UI.' It immediately distinguishes from sibling `picsart_list_models` by specifying that tool renders a picker. This removes 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?

Explicitly states when to use: 'when YOU (the assistant) need catalog knowledge for your own reasoning...' and when not to: 'When the user wants to SEE or browse models visually, use `picsart_list_models` instead.' It also names alternatives for related tasks: `picsart_model_params` for full schema, `picsart_preflight` for cost. Clear when/when-not.

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, destructiveHint. The description adds valuable context: 'Read-only; spends no credits and works without authentication' and describes the user interaction flow (user taps, pick returns as JSON). No contradiction with annotations.

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

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

The description is well-structured: first sentence defines purpose, then usage guidelines, then constraints, then alternatives. Every sentence adds value. No redundancy or verbosity. Length is appropriate for the complexity.

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

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

Given the tool's role as a decision board with rich input schema and annotations, the description covers all necessary aspects: when to call, how to prepare candidates, constraints, what happens (user picks, JSON in conversation), read-only nature, and return of normalized board payload. No gaps.

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

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

Schema description coverage is 100% with detailed field descriptions. The description adds meaning beyond schema by explaining how to use parameters: 'write each bestFor line for THIS project rather than as a spec sheet', 'mark at most one as recommended', and provides example for purpose. This guidance helps the agent fill parameters correctly.

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

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

The description clearly states the tool opens a Model Choice board for user decision, with a specific verb ('Opens'), resource ('Picsart Model Choice board'), and outcome. It distinguishes from siblings: 'For free-form catalog browsing use picsart_list_models instead; this board is a decision, not a catalog.'

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

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

Explicitly states when to call ('BEFORE the first charged generation of a project, after narrowing the catalog with picsart_model_catalog'), how to prepare candidates (2-6, bestFor per project, at most one recommended), and when not to use it ('Do not pick a model silently...'). Also provides alternative: picsart_list_models for catalog browsing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by stating 'Read-only; spends no credits and works without authentication', which is congruent with annotations. It also describes the return structure, providing additional behavioral context beyond what annotations offer.

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 and well-structured. It starts with the primary purpose, then provides usage guidelines, required input, an example, and a note on credits/auth. Every sentence adds value, though it could be slightly more terse 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?

Given the simple tool (1 param, output schema exists), the description is complete. It covers input, output structure, usage context, what the tool does and does not do, and behavioral notes (read-only, no credits). With an output schema present, there's no need to detail return values further, but the description still outlines the schema shape.

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

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

Schema coverage is 100% with one parameter 'model' fully described. The description adds an example usage '{ model: "flux-2-pro" }' and mentions the type, which slightly enhances understanding beyond the schema alone. The baseline for high coverage is 3, and the example justifies a 4.

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

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

The description clearly states it 'Returns the parameter schema for a specific Picsart model' and distinguishes from siblings by explicitly saying 'Do NOT use it to discover which models exist (use picsart_list_models) or estimate cost (use picsart_preflight)'. The verb 'Returns' and resource 'parameter schema' are specific and unambiguous.

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

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

The description provides explicit when-to-use guidance: 'once you have a model id and need to construct the params payload for picsart_generate or feed picsart_preflight with a candidate object'. It also gives when-not-to-use: 'Do NOT use it to discover which models exist (use picsart_list_models) or estimate cost (use picsart_preflight)'. Includes required input and an example.

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 (readOnlyHint, idempotentHint, destructiveHint), the description adds valuable context: 'Read-only; spends no credits and works without authentication' and the return shape '{ items, total, truncated }'. This explains the tool's side-effect profile and runtime behavior clearly. The 'create/save' language refers to the widget's UI actions, and the read-only clarification resolves any ambiguity.

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 dense, front-loaded paragraph where every sentence earns its place. It moves from core purpose to use cases, exclusions, input, return value, and behavioral characteristics in logical order. Despite its length, there is negligible waste and the structure makes it 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 the tool's complexity (many embedded capabilities), the description covers purpose, use cases, boundaries, parameter count, return type, authentication, and credit impact. The presence of an output schema means return-value details are already structured, and the description complements it rather than repeating it.

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

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

The tool has zero parameters and the schema coverage is 100%, so there is no parameter syntax to clarify. Per the calibration baseline, 0 params warrants a 4. The description appropriately notes 'Takes no input,' which adds useful confirmation without redundancy.

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 ('Opens the Picsart Music Studio') and enumerates concrete capabilities (browse models, compose, generate/play, create album art, revisit tracks, save to folder). It strongly distinguishes itself by explicitly listing what it does NOT do (editing audio, TTS, image/video generation), which separates it from sibling tools like picsart_media_apply_effect or picsart_generate.

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

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

Explicitly states when to use: 'Use when the user wants to MAKE music, a song, a soundtrack, a jingle, or sound effects.' It also gives clear exclusions: 'Does NOT edit existing audio... not for text-to-speech / voice cloning or image/video generation.' This provides strong when-to-use and when-not-to-use guidance, even without naming alternative tools directly.

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, and the description aligns with these. It adds non-obvious behavioral details: the validation is local and requires no auth, the credits quote is a dry-run cost, and it returns null when pricing is unavailable or unauthenticated. This goes beyond the annotation signal to disclose actual side-effect-free 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 compact yet information-dense, using numbered flow, an example, and a return format spec. Every sentence adds value: purpose, usage timing, exclusions, required inputs, example, output semantics. No fluff or repetition of schema fields.

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

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

Given the tool's moderate complexity (nested params, optional errors, conditional credits) and the presence of an output schema, the description covers all necessary context: what valid/errors mean, when credits is null, and auth implications. It is complete enough for an agent to invoke correctly without further research.

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 both parameters and notes that params should include the prompt, so baseline is 3. The description adds a concrete example (`{ model: "flux-2-pro", params: { prompt: "a cat in a hat", aspectRatio: "1:1", count: 1 } }`) and clarifies that the prompt goes inside the params object, which is useful for correct invocation. It doesn't over-explain since schema coverage is 100%.

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-plus-resource statement: 'Free pre-flight check before `picsart_generate`'. It clearly enumerates the tool's two functions (validate params, quote cost) and distinguishes it from siblings by explicitly naming alternatives (`picsart_model_params`, `picsart_generate`). No ambiguity remains about what this tool does.

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

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

The description gives explicit timing: 'Use this after assembling params ... and before generating'. It also provides direct exclusions with named alternatives: 'Do NOT use it to look up which params a model accepts (use `picsart_model_params`) or to actually generate (use `picsart_generate`)'. This is textbook usage guidance.

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

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

While annotations indicate readOnlyHint=false and destructiveHint=true, the description adds significant context: auto-picks model, requires Authorization, spends credits, handles local files, and explains the return format (single JSON text block, no resource_link blocks, widget as source of truth). 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 detailed but every sentence adds value: purpose, usage, exclusions, parameters, example, return structure, and auth. Well-organized and front-loaded with the core action.

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

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

For a tool with auth, credit costs, model selection, and output quirks, the description covers all necessary context. Even with an output schema, it explains the return structure and critical integration details (single JSON block, no duplicate result blocks).

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