AppLaunchFlow

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

Annotations already declare idempotentHint=true, destructiveHint=false, and readOnlyHint=false, so the description's idempotency sentence largely restates structured data. It does add one piece of beyond-schema context — that additions are 'subject to plan limits' — but leaves unexplained what happens when the limit is hit (error vs. silent skip).

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

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

Two efficient sentences with the core action front-loaded and the idempotency note secondary. 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?

Given an output schema exists, return values needn't be explained, and annotations cover the safety profile. The remaining gap is behavioral nuance around plan-limit failures and store selection, which the description gestures at but does not resolve.

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

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

Schema coverage is only 33%, so the description should compensate more than it does. It maps loosely onto all three parameters ('specified competitor apps' → appIds, 'project's keyword tracking' → projectId, 'one store' → storeProvider), but adds no array-size, format, or defaulting detail beyond what the schema and storeProvider's own description already provide.

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

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

The description states a specific verb and resource — adding competitor apps to a project's keyword tracking — which clearly separates it from add_keywords (keywords) and suggest_keyword_competitors (suggestions). It could go further by naming those siblings explicitly, but the resource distinction is strong enough for correct selection.

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 phrase 'for one store' and 'subject to plan limits' hints at the operating context, but the description never says when to prefer this over suggest_keyword_competitors or how it relates to add_keywords. Usage is implied rather than directed.

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

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

Annotations only declare the mutation/safety profile; the description adds substantial context beyond them — keyword-country pairs count against a quota, oversized batches are rejected atomically in full ('rejected in full'), and rankings arrive asynchronously. These are exactly the operational traits an agent needs before invoking.

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

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

Five sentences, action verb front-loaded, and every sentence carries a distinct fact (identity resolution, quota, atomicity, no-app behavior, async rankings). Dense but not padded.

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

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

With an output schema present, the description needn't explain return values, and it covers the remaining gaps an agent needs: quota limits, all-or-nothing batch rejection, defaults for store/country, and the async ranking caveat.

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

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

Schema coverage is already 86%, so the schema carries most parameter meaning. The description still adds value by explaining the appId/storeProvider defaulting logic ('resolve from project metadata unless overridden') and the keywords × countries quota interaction, which the schema alone doesn't state.

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

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

Opens with a specific verb+resource: 'Adds keyword tracking for the requested stores/countries.' This clearly distinguishes it from suggest_keywords, list_keywords, and remove_keywords by scope of operation, though it never names a sibling explicitly.

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

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

Provides usable context for calling it: identity resolves from project metadata unless overridden, and projects without a linked app can still track terms. It stops short of stating when to prefer this over suggest_keywords or add_keyword_competitors, so no explicit alternative routing.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the bar is lower, yet the description still adds real value: it scopes the destruction ('replaces only the targeted translation images'), states that unfilled frames retain their images, that excess sources are reported, and that assignment follows document order. Only auth/permission or failure-mode behavior is left unstated.

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 dense sentences, front-loaded with the core action, then sources, then ordering/retention semantics, then preview vs apply. No filler and no restatement of the title.

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?

Output schema exists, so return values need not be explained, and the preview mode's return behavior is noted anyway. For a 9-parameter nested-object tool the only real gap is how the three source parameters interact when more than one is provided, plus what platform/deviceType change.

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

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

Schema coverage is only 33%, so the description carries weight here, and it does explain the three source-input parameters (localeFolders, screenshotPathsByLanguage, screenshotPaths) by describing them as alternative source modes. It does not state precedence or mutual exclusivity when several are supplied, and platform/deviceType go unmentioned.

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

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

States a precise verb and resource: assigning language-specific screenshot assets to existing translated device frames. The three source modes (locale folders, per-language paths, shared path list) further pin down what the tool consumes, which distinguishes it from siblings like upload_screenshots, apply_screenshot_style, or preview_screenshots.

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

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

Clearly splits the two operating modes — preview returns assignments without saving, apply replaces only targeted translation images — which tells the agent when to use each. It stops short of routing to sibling tools (e.g., when to use preview_screenshots or upload_screenshots instead) or naming prerequisites such as frames already being translated.

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

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

Annotations already declare this as destructive, non-readonly, and non-idempotent, so the baseline burden is lower. The description adds valuable behavior beyond annotations: the prior variant is retired only after the new variant saves successfully, and the result includes an editor link. It could say more about failure behavior or irreversibility, but the core transactional behavior is disclosed.

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

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

The description is two front-loaded sentences with no wasted text. It states the main action first and then adds the important replacement condition.

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 output schema exists, so the description need not document return values in depth, and annotations cover the destructive nature of the operation. Still, for a destructive mutation with three required but poorly documented parameters, the description leaves important parameter semantics and prerequisites unclear.

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%, so the description must compensate for undocumented required parameters. It adds meaning for replaceVariantId, explaining that the prior variant is retired only after a successful save, but it does not clarify projectId, candidateId, or candidateKey, including the distinction between the candidate identifier and its hash-like key.

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

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

The description states a specific verb and resource: it saves a prepared promo-video candidate as a variant and returns an editor link. It is clear what the tool does, though it does not explicitly distinguish itself from siblings such as create_variant or preview_promo_video.

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

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

The word 'prepared' implies a candidate must first exist, and the replaceVariantId sentence gives a conditional usage rule. However, the description does not say when to choose this tool over related tools like create_variant, preview_promo_video, or clear_promo_video, leaving alternatives implicit.

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

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

Annotations already declare non-destructive, non-idempotent, closed-world behavior, so the bar is lower and the description does add real context: cached layout reuse (no regeneration cost) and 'Existing variants are preserved'. However, it does not say what happens on an invalid/expired catalogKey, whether repeated calls with the same inputs produce duplicates (relevant given idempotentHint=false), or what the editor link points to.

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

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

Three short sentences, front-loaded with the action, then the caching/no-regeneration trait, then the safety reassurance. Little waste; the only minor redundancy is restating the return of an editor link that the output schema likely covers.

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

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

With annotations covering safety profile and an output schema covering return values, the description only needs to convey the composition semantics and it does. The remaining gap is the two required parameters' semantics and the precondition on prepare_screenshot_styles.

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 67%, with descriptions for projectId/generationId aliasing, deviceType and paletteMode; the two required params, catalogKey and templateId, are undocumented in the schema. The description only gestures at them ('prepared personalized catalog', 'specified template'), adding no format, provenance, or lookup guidance for the mandatory 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?

Specific verb and resource: 'Creates a new screenshot variant' from 'a prepared personalized catalog and the specified template/palette selection'. The phrase 'Reuses cached candidate layouts without another generation' implicitly separates it from the prepare/generate step, but no sibling is named outright, so an agent must infer the pairing from the sibling list.

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

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

The mention of a 'prepared' catalog hints that prepare_screenshot_styles must run first, and 'specified template/palette selection' implies the selection step, but neither is stated as a precondition. There is no explicit when-to-use/when-not or named alternative (create_variant, apply_locale_screenshots).

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

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

With annotations already declaring readOnlyHint=false, idempotentHint=false and destructiveHint=false, the description adds real value: it discloses that all supported formats are produced, that cached layouts are reused without a new generation, and that an editor link is returned. It omits whether repeated calls create duplicate variants or what caching invalidation looks like, which matters for a non-idempotent mutation.

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

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

Two sentences, front-loaded with the action and the source of inputs, then the side effects. Tight overall, though 'includes all supported formats' is slightly vague and could be more precise about what set of outputs that means.

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

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

An output schema exists, so return values need little explanation, and the caching behavior is disclosed. However, for a non-idempotent creation tool with six parameters, the description leaves open whether it overwrites an existing variant, what happens on repeat calls, and how catalogKey/templateId are obtained.

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 67% and the schema already documents projectId/generationId alias, paletteMode and primaryFormat. The description adds nothing about catalogKey or templateId, the two undocumented required parameters, so an agent gets no help on where those values come from beyond 'prepared catalog and selected style'.

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

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

States a specific verb+resource: creates a new social-graphics variant from a catalog key and selected style, which clearly separates it from siblings like render_graphics or prepare_social_graphics_styles. It doesn't name the sibling it depends on explicitly, so the differentiation is implied rather than 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?

'from a prepared catalog and selected style' hints that prepare_social_graphics_styles must run first, but the prerequisite is never named and there is no when-not guidance (e.g. vs render_graphics or save_graphics). The usage context is inferable but not explicit.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds real context beyond that: the picker is 'cached', results are a URL plus format specs, and the never-generate/apply/create clause reinforces the boundary for an agent tempted to treat this as a generator. No permission or pagination notes, but the read-only surface is well clarified.

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

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

Three sentences, front-loaded with what it returns, then the mode split, then the negative boundary. No filler. 'V1/V2 previews' is mildly opaque jargon, a small deduction but the structure is efficient.

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

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

An output schema exists so return values need no explanation, annotations cover safety, and the schema fully documents parameters. The description's job reduces to explaining the two invocation modes, which it does. Slight gap in not stating what happens with a stale or expired catalogKey, but otherwise complete for a read-only browser.

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

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

Schema description coverage is 100%, so all seven parameters including the projectId/generationId aliasing and the catalogKey pairing are already documented. The description adds only the semantic outcome of combining project + catalogKey (personalized vs. static), which the schema itself largely states. Baseline 3 is appropriate when the schema carries the parameter burden.

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

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

States a specific verb and resource (displays the cached social-style picker) and what it returns (gallery URL and format specifications). It distinguishes its two modes (personalized preview with project+catalogKey vs. static discovery) but never names the sibling browse_templates or apply_social_graphics_style it should be contrasted with, leaving sibling differentiation to inference.

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

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

Gives an explicit condition for each mode: 'A project plus prepared catalogKey enables personalized V1/V2 previews; without a catalog it provides static discovery.' It also states what it never does (generates options, applies a style, creates a variant), which usefully excludes downstream actions. It stops short of naming which tool to use instead for those excluded actions, so no full alternatives map.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world. The description adds real context beyond them: it discloses that it returns a cached gallery URL rather than rendering anything, and that personalization requires a prepared catalogKey. Useful behavioral detail, though it doesn't cover failure modes or rate/caching behavior.

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

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

Three sentences, front-loaded with the core action and return, then the mode distinction, then the negative scope. No wasted prose; each sentence carries distinct information.

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

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

Output schema exists so return values needn't be explained, annotations cover safety, and the schema fully documents params. The description supplies the one thing structured fields can't: the decision logic between static discovery and personalized previews. Nothing essential is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description goes beyond individual param docs by explaining the combined effect of projectId+catalogKey (personalized vs static) and referencing device and template subset selection, adding semantic meaning the schema fields document only in isolation.

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

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

States a specific verb and resource: it 'displays the cached screenshot-style picker and returns its gallery URL.' The 'screenshot-style' qualifier implicitly distinguishes it from browse_social_templates, but the sibling is never named, so an agent must infer the split rather than read it.

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

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

Explains two modes: 'project plus prepared catalogKey enables personalized V1/V2 previews; without a catalog it provides static discovery,' and the closing sentence rules out generating options, applying a style, or creating a variant (routing away from apply_screenshot_style/create_variant). Clear usage context, though it never names the sibling alternatives explicitly.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds real value by specifying what is destroyed ('removes its current video content') and that the variant itself is not replaced, though it does not state whether cleared content is recoverable or what state the variant is left in.

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

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

Two short sentences with the resource scope front-loaded and the disambiguation second. Every clause carries information; nothing is redundant or padded.

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

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

An output schema exists and annotations cover the destructive/idempotency profile, so return values and safety need not be restated. However, for an irreversible mutation with an optional targeting parameter, the missing guidance on the optional variantId and reversibility leaves a meaningful 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?

Schema description coverage is 0%, so the description carries the full burden for two parameters, and it says almost nothing about them. It implies variantId targets a specific variant but never explains the effect of omitting the optional variantId (e.g., whether it defaults to the active variant) or what projectId must reference.

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

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

States a specific verb (clears) and resource (the specified promo-video variant's saved configuration), which is more precise than the title alone. The clause 'rather than creating a new variant' rules out the most plausible misinterpretation, though it contrasts with a behavior rather than naming sibling tools like delete_variant or generate_promo_video.

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

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

No explicit when-to-use or when-not guidance and no named alternatives, even though siblings such as delete_variant, update_promo_video, and apply_promo_video_candidate clearly compete for similar intents. The only guidance is the implicit clarification that this is not a variant-creation operation.

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

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

Goes beyond the annotations in two useful ways: it explains that a caller-supplied folderId makes retries reuse the same folder (a concrete idempotency mitigation not conveyed by idempotentHint=false), and it states the blast radius — storage paths and saved designs are unchanged. What's missing is failure behavior (what happens on a second call with the same folderId, or a duplicate name), which matters for a mutation tool.

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

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

Three short sentences, front-loaded with the action and scope, followed by the retry contract and the non-effect statement. Every sentence carries distinct information and nothing is repeated from the schema or annotations.

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

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

For a non-destructive create with an output schema (so no return-value explanation needed) and annotations covering the safety profile, this is nearly complete. The remaining gap is the failure/duplicate path for folderId and name, which an agent calling a create tool would want before retrying.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning; it explains folderId's purpose as a caller-supplied retry key and clarifies locale is optional, which the schema does not. However projectId, name (1–60 chars), and deviceType are never explained, and the interaction between deviceType and platform is left to the enums.

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

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

States a specific verb (creates), a specific resource (screenshot folder), and its scoping dimensions (device, platform, optional locale). No sibling competes for the same resource — the other folder tools are list/rename/delete/set_locale — so the resource name alone differentiates it. It stops short of explicitly naming an alternative, hence 4 not 5.

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

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

Usage is implied rather than stated: the agent can infer this is the setup step before uploading or listing screenshots in a folder, but no sentence says when to use this versus prepare_asset_upload/upload_screenshots or list_asset_folders. No prerequisites (does projectId need to exist first? must name be unique within the project?) and no when-not guidance are given.

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

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

Goes beyond the annotations by disclosing that existing variants are preserved (reinforcing non-destructiveness), that the call returns the new variant plus an editor link, and that motion duration is read server-side from video length. This is meaningful behavioral context, though permission requirements are unstated.

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 front-loaded sentences that each carry information: creation semantics, no-upload-needed, supported devices, preservation guarantee, and return value. No filler or redundancy.

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

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

With a rich schema and an output schema, the description only needs to orient the agent, which it does by naming inputs, device scope, and return value. Minor gap: no explicit guidance on prerequisites or relationship to preview/update tools.

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

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

Schema description coverage is 100%, so the schema already documents every parameter thoroughly (device choices, preset meanings, outputRatio default, screenshotPath examples). The description largely restates device support and adds little syntax or semantics beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb and resource: creates a new mockup-animation variant from a scene preset plus screenshot/recording. The required-input framing implicitly distinguishes it from siblings like create_variant and update_mockup_animation, though no sibling is named explicitly.

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

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

Adds a helpful note that 'a dedicated mockup upload is not required' and that existing variants are preserved, which clarifies safe usage. But there is no explicit when-to-use guidance, no mention of preview_mockup_animation as a precursor, and no routing versus create_variant or generate_mockup_motion.

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

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

Annotations already mark this as a non-read-only, non-idempotent, non-destructive open-world operation, and the description adds useful behavioral context about App Store import, platform defaults, and returned project ID and hub URL. It does not disclose auth requirements, rate limits, or side effects beyond creation, but the annotation coverage lowers the burden.

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

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

The description is four sentences, front-loaded with the core action and followed by source modes, defaults, return values, and exclusions. Every sentence adds distinct information, and there is no boilerplate or repetition.

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

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

Given nine parameters, nested metadata, enums, full schema descriptions, annotations, and an output schema, the description covers the essential scope, defaults, and return values. It does not need to re-explain parameter details, though it could more explicitly mention creation prerequisites or when a project should already exist.

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

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

Schema description coverage is 100%, so the schema already fully documents all nine parameters, including the appName/appStore relationship and platform defaults. The description reinforces the main source options and platform default but adds no syntax or conditional details beyond the schema, 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 states a specific verb and resource: it 'Creates a project' and explains the two supported creation modes (app name or Apple App Store import). It also distinguishes the operation from adjacent actions by noting that it does not generate a design or publish to a store, so an agent can identify it without inspecting sibling schemas.

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

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

The description gives clear usage context: create a project from an app name, or import metadata/icon from an App Store listing, with iOS as the default platform. It also provides a partial when-not boundary by saying it does not generate a design or publish. It stops short of naming sibling alternatives such as duplicate_variant or create_variant.

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

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

Annotations only declare the generic safety profile (readOnly=false, destructive=false, idempotent=false); the description adds genuinely new behavior: the variant is created empty and inactive, no design is generated or copied, and the call consumes the plan's variant limit. That quota side-effect is exactly the kind of context an agent cannot get from structured fields. It stops short of stating permissions or whether creation is reversible.

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, zero filler, with the most decision-relevant facts (empty, inactive, no design copy) front-loaded before the quota caveat.

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

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

An output schema exists and annotations cover safety, so the description only needs to convey creation semantics — which it does, including the empty/inactive nature and the plan-limit cost. It omits any pointer to the correct sibling for design-populated variants, a small remaining gap for a create tool with four siblings in the variant family.

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 60% and the two documented properties (projectId/generationId alias, setActive) carry rich, well-explained constraints. The description's 'named, inactive' wording loosely maps to label and setActive but adds no syntax, defaults, or requiredness information beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource with meaningful qualifiers: 'Creates an empty, named, inactive content-type variant.' The clause 'Does not generate or copy a design' implicitly separates it from duplicate_variant, but no sibling is named explicitly, so an agent must infer the routing.

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

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

The description never says when to choose this over duplicate_variant or how it relates to list_variants/set_active_variant. The only routing advice ('fill the variant, then call set_active_variant') lives in the setActive schema property, not in the description, leaving the prose with no usage guidance at all.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, and the description adds the crucial extra context annotations cannot express: only the grouping is destroyed, not the underlying files, storage objects, or saved-design references. It omits reversibility and permission/auth requirements, keeping it below 5.

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

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

Two tight sentences with the primary effect first and the scope caveat second; every clause carries information an agent needs.

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?

Output schema exists so return values need no explanation, and annotations cover the safety profile; the description's main job is clarifying blast radius, which it does well. The remaining gap is the complete absence of parameter meaning for a destructive, non-idempotent operation.

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

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

Schema description coverage is 0% — folderId and projectId have type/format constraints but no semantic documentation — and the description says nothing about either parameter. It neither explains what folderId identifies nor how projectId scopes the operation, so it fails to compensate for the coverage gap.

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

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

Specific verb (deletes) plus specific resource (screenshot folder) and an explicit statement of the effect on contained files (ungroups them). The 'does not delete asset files' clause separates it from delete_assets, though no sibling is named explicitly.

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

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

Usage is implied — you call this to remove a folder while keeping the assets — and the negative clause implicitly routes file deletion to delete_assets. But there is no explicit when-to-use statement, no prerequisite (e.g. folder must be empty or exist), and no named alternative.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds real value beyond that: permanence, irreversibility, and the blocking precondition from saved-design references. It omits batch semantics for the up-to-50 paths (partial failure vs all-or-nothing), which is the main remaining gap.

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

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

Three short sentences, front-loaded with the destructive nature, and every sentence adds a distinct fact (what is removed, what blocks it, irreversibility). 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?

An output schema exists, so return values need not be explained. However, for a destructive batch mutation over up to 50 paths, the description should address what happens when some paths are blocked by saved-design references and whether projectId scopes the operation.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it says nothing about either parameter. 'Specified asset records' only loosely hints that paths are asset paths; projectId scoping and the 1-50 path batch limit are never mentioned.

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

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

States a specific verb ('Permanently removes') and resource ('asset records and storage objects'), which distinguishes it from folder/project/variant deletion siblings. It does not explicitly name those siblings, but the resource scope is unambiguous.

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

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

Usage is implied by the destructive verb rather than stated. The one real routing signal is the precondition 'Saved-design references block deletion', which tells an agent when the call will fail, but no alternatives (e.g. replace_asset, move_assets, delete_asset_folder) are suggested for adjacent tasks.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so 'This is a destructive project operation' merely restates structured data. The description omits genuinely useful behavior: whether deletion is permanent/irreversible, whether it cascades to variants, assets, screenshots, or layouts, and whether confirmation or special permissions are required.

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

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

Very short and front-loaded, but the second sentence is pure redundancy against the annotations, so half the text earns no place. Efficient in size, weak in density of 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?

An output schema exists so return values need not be explained, but for an irreversible destructive operation with cascading side effects and an undocumented id parameter, the description says nothing an agent needs before invoking it. It is under-specified for the risk level of 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?

One required parameter with 0% schema description coverage; the schema gives only type/format/pattern, not what a project is or where to obtain the id. 'The specified project' adds nothing beyond the parameter name, and does not point the agent to list_projects or get_project.

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

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

States a specific verb and resource ('Deletes the specified project'), which is unambiguous on its own. It does not distinguish itself from similar destructive siblings such as delete_assets, delete_variant, or delete_asset_folder, so an agent gets no help disambiguating scope.

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

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

No guidance on when to use this versus the other delete tools, no prerequisites (where the projectId comes from, e.g. list_projects or get_project), and no warning about what must be done before deleting. Only implied usage from the name.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, but the description goes well beyond them: it discloses the cascade (all content and translations are removed), irreversibility, and the post-condition that deleting the active variant promotes the newest remaining one, surfaced as promotedVariant. That side effect is exactly the kind of behavior an agent cannot infer from the structured fields.

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

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

Three short sentences, front-loaded with the destructive action and its irreversibility, then the side effect. No filler and no repetition of the title.

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

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

For a destructive 4-parameter tool with an output schema, the description covers the essential risk profile and the promotedVariant return value. The remaining gap is parameter-level: nothing explains how variantId and contentType relate or what happens if contentType mismatches, but with annotations carrying the safety profile this is a minor omission.

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

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

Schema coverage is only 50%, and the description contributes nothing about the parameters — variantId has no description at all and contentType's enum has no explanation of whether it must match the variant's actual type. Only confirm and projectId are documented, and that documentation lives entirely in the schema, not the description.

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

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

States a specific verb and resource ('Permanently deletes the specified variant') plus the cascade scope ('all of its content and translations'), which is far more precise than the title alone. It does not distinguish itself from nearby siblings like delete_project, delete_assets, or duplicate_variant, so it stops short of a 5.

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

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

Usage is only implied: the tool is for removing a variant that is no longer needed, and 'Cannot be undone' serves as a caution. There is no explicit guidance on when to choose this over delete_project, delete_assets, or duplicate_variant, and no prerequisites (e.g., that confirm must be set) are stated in the description.

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

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

Annotations establish a non-read-only, non-destructive, non-idempotent mutation, and the description adds meaningful context beyond them: the copy is created inactive with a copy label, the original is preserved, and the operation consumes a plan variant slot. It stops short of saying whether repeated calls create additional copies (non-idempotent) or what error occurs at the plan limit.

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

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

Three short sentences, front-loaded with the action and result, then the side effects, then the return. No filler and nothing repeated from structured 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?

For a one-parameter mutation this covers action, side effects, plan impact, and return shape (the copy and editor link). A pointer to set_active_variant for activating the resulting inactive copy would close the remaining 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?

Only one parameter (variantId) and the schema provides zero description coverage. The description implies the ID refers to the source variant being copied, but never states that explicitly or clarifies whether the ID must belong to the current project. Baseline 3 given the single obvious parameter.

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

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

States a specific verb (copies) and resource (a variant's saved content and translations) with the resulting artifact (a new inactive variant with a copy label). It is clearly distinguishable from create_variant in intent, though it never names the sibling to make the contrast explicit.

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

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

The described behavior implies the use case (clone an existing variant rather than build one from scratch), but there is no explicit 'use this when…' guidance and no mention of alternatives such as create_variant for a from-scratch variant. The plan-limit warning hints at a pre-condition but does not frame it as guidance.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, yet the description still adds meaningful context: an accepted job consumes one API export allowance (a cost), and idempotencyKey re-identifies the same request across retries rather than creating a new job. That explains *how* idempotency behaves, which the hint alone does not.

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

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

Four tight sentences, front-loaded with the action and return value, then preconditions, then cost, then idempotency. Every sentence adds something, though the second 'uses one allowance' sentence restates the allowance concept already introduced.

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

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

With an output schema present, return values needn't be explained, and the description still names exportJobId. An agent has the action, constraints, cost, and retry semantics; only the follow-up polling path (get_mockup_animation_export) is left implicit for this async export 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 only 33%, so the description must carry weight. It does explain idempotencyKey semantics (same key = same request across retries), while quality and variantId are covered by the schema and fps/format are self-evident enums. The gaps (fps trade-off, format selection) are minor, but the compensation is partial.

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

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

States a specific verb and resource: 'Starts an MP4/WebM export of a saved mockup animation and returns exportJobId.' The word 'saved' and the returned job id distinguish it from preview_mockup_animation and point toward get_mockup_animation_export for polling, though no sibling is named explicitly.

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

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

It states the preconditions for server exports (opaque background, duration under thirty seconds, available allowance), which is real gating guidance, but it never says when to pick this over preview_mockup_animation or export_promo_video, nor what to do after the job is accepted. Usage is implied rather than routed.

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

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

Annotations already cover idempotency, non-readOnly, non-destructive, and closed-world. The description adds real value beyond them: it discloses that a job consumes one API export allowance, enforces a 30-second duration limit, and returns an exportId — billing/limit context an agent needs before calling.

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

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

Five short sentences, each carrying a distinct fact (format, placements, duration limit, allowance/return, idempotency). Front-loaded with the core action; no filler, though the placement sentence is slightly dense.

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

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

For an 8-param mutation tool with an output schema and full annotations, the description covers the essential behaviors (cost, duration precondition, exportId, idempotency retry semantics). The only material gap is the undocumented size/quality parameters.

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

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

Schema coverage is only 25%, so the description must compensate more. It clarifies format (MP4/WebM), the four category placements, variant, and language, but leaves size, quality, projectId, and variantId meaning unexplained. Partial compensation for a low-coverage schema.

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

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

States a specific verb and resource: 'Starts an MP4/WebM export of a saved promo-video variant and language.' It is distinguishable from generate_promo_video and preview_promo_video by the word 'export', though it never explicitly names those siblings or contrasts with them.

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 a hard precondition ('Server duration must be under thirty seconds') and notes the one-allowance cost, but never says when to prefer export over preview_promo_video or when to poll get_promo_video_export for the result. Usage is only implied.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known; the description adds the key behavioral detail that nothing is persisted and no pixels are rendered. It does not mention non-determinism despite idempotentHint=false, which would be useful since drafting from a prompt likely varies across calls.

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 tight sentences with no filler; the generation action comes first and the non-persistence caveat follows. Every clause earns its place.

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

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

An output schema exists, so return values need not be explained, and the 'does not save or render' note covers the main ambiguity. However, for a drafting tool in a crowded animation toolset, the missing link to create_mockup_animation and any prompt-shaping guidance leaves the definition only minimally complete.

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

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

Schema description coverage is only 33% — only deviceKind is documented, and the description adds nothing about it. The two required parameters (prompt, projectId) are never discussed, so the description gives no guidance on what kind of motion prompt to write despite the 3–600 character constraint.

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

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

The description uses a specific verb and resource ('Drafts mockup keyframe data from a motion description') and clearly states what the output is and is not. It does not name or distinguish itself from close siblings such as create_mockup_animation, preview_mockup_animation, or update_mockup_animation, so an agent must still infer the boundary.

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?

Saying it 'returns configuration data without saving an animation or rendering video pixels' implies a generate-then-create workflow, but the description never says when to pick this over create_mockup_animation or that its result feeds into it. Usage is only implied, not stated.

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

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

Annotations only cover the safety profile (non-read-only, non-idempotent, non-destructive, closed-world), while the description adds real behavioral context: background/asynchronous preparation, reuse of in-flight work, three transient candidates, a picker that updates on completion, and that nothing persists until an explicit selection. It stops short of describing lifecycle details such as picker expiry or re-invocation cost.

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 key behavior (three transient candidates, picker returned, selection required to persist) is front-loaded in the first two sentences, and the parameter notes are compressed into one closing sentence. It is dense but nearly every clause carries information; no filler.

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

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

For a six-parameter, asynchronous generation tool with an output schema and full annotation coverage, the description supplies the essentials: transience, async completion, and the save boundary. Missing only peripheral detail such as picker URL lifetime or what repeated invocation does to in-flight preparation.

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 every parameter is already documented, making 3 the baseline. The description adds a little meaning for replaceVariantId (it applies only after the new selection saves) and states that selectedScreenshotPaths restricts candidate inputs, but much of this restates the schema's own wording.

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

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

The description names a specific verb and resource: it starts or reuses preparation of three transient promo-video candidates and returns an embedded picker or its URL. That is far more specific than the title, though it never names the natural siblings (preview_promo_video, get_promo_video_generation, apply_promo_video_candidate) to draw the boundary explicitly.

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

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

The workflow is implied ('Only an explicitly selected candidate becomes a saved variant', replaceVariantId only with explicit user approval), which tells the agent this is a non-committal preparation step. However, there is no explicit when-to-use-this-vs-that guidance against preview_promo_video or get_promo_video_generation, so the agent must infer the routing.

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

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

Annotations flag destructiveHint=true, and the description earns that flag: it explains that replaceVariantId retires a prior variant only after the new one successfully saves, which is exactly the destructive surface. It also discloses the non-publishing boundary. It does not state that each call produces a new variant (relevant given idempotentHint=false), which is the remaining gap.

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

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

Three short sentences, front-loaded with the core action, followed by the destructive-parameter caveat and the scope boundary. Nothing is redundant and nothing needed is buried.

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

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

With an output schema present and rich annotations, the description covers purpose, destruction semantics, and the publish boundary. What's missing is small but real: whether the generated variant becomes active, and what project context is drawn from. Not disqualifying, but not fully complete.

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

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

Schema coverage is 75% and three of four parameters carry descriptions, so the schema does the heavy lifting. The description adds one meaningful nuance — the replacement's ordering/success semantics — but says nothing about projectId (undocumented) or how competitorAppIds/provider shape the output. Baseline 3 is right.

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

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

The description names a specific verb and resource — generating store-listing (ASO) copy as a new variant — and clarifies it does not publish anywhere. That separates it from update_store_listing and translate_store_listing, though it never explicitly contrasts with create_variant, which also creates variants.

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 line 'Does not publish text to Apple or Google' is a useful negative boundary, and replaceVariantId is scoped to post-success replacement. But there is no explicit routing guidance (e.g., use update_store_listing to edit an existing variant, or create_variant for non-copy variants), so the agent must infer when this is the right call.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds genuinely useful context beyond them: it reveals that some listed features exist only in the dashboard (i.e., not callable via MCP) and that links are project-scoped when a project ID is supplied.

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

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

Three short sentences, front-loaded with what is returned, followed by the parameter behavior and the read-only note. Nothing redundant or padded.

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

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

A simple, zero-required-parameter read tool with an output schema, so return values need no explanation. Scope, the single parameter's effect, and the read-only nature are all covered; only an explicit 'call this first to discover features' cue 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 0%, so the description carries the burden for projectId — and it does, stating the parameter is optional and that it changes the returned links to be project-specific. The UUID format/pattern is left to the schema, which is fine.

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

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

States a specific verb and resource: returns supported MCP feature areas and tools, plus dashboard/editor links. This is clearly a discovery/introspection tool distinct from every sibling, though it does not explicitly contrast itself with them.

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?

Usage is implied — an agent would infer this is the feature-discovery call — and the note that an optional project ID supplies project-specific links hints at a conditional call. But there is no explicit 'use this when / don't use this for' guidance or statement about when the project-scoped variant matters.

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=false and openWorldHint=false, so the safety bar is low. The description still adds real value by asserting the data is built-in and needs no project access, which explains why the call succeeds in an unauthenticated/empty context; it stops short of stating cost, latency, or response size.

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

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

Two sentences, zero preamble, with the core identity front-loaded and the content inventory second. The second sentence is a dense list rather than padding, though it could have carried the symbol-vs-feature behavior instead of only enumerating definition categories.

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

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

An output schema exists, so return-format explanation is rightly omitted, and access requirements are covered. What remains missing is the two-step workflow the tool implies — call once to read the index, then again with a 'symbol' — which matters for an agent planning a lookup sequence.

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 50% schema coverage, the description partially compensates: it names the four feature values ('screenshots, social graphics, promo videos or mockups') matching the feature enum. However, it never explains the interplay between the two parameters — whether omitting 'symbol' returns the whole index, and whether 'symbol' narrows output to a single definition — leaving the primary caller decision undocumented.

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

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

States a specific verb and resource ('Returns the built-in editing reference') and enumerates exactly what the payload contains: symbol index plus field, enum, coordinate, validator and catalog definitions. No sibling tool serves this lookup role, so the definition is unambiguous on its own.

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 establishes prerequisites ('available without project access or external resource browsing') but never says when an agent should call this instead of proceeding directly, nor that it is the discovery step preceding schema-dependent calls like save_layout or update_graphics_settings. Usage is implied by the resource name rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so 'Read-only.' is pure repetition. The one genuine addition is 'Unsaved derived formats are absent,' which tells the agent results are filtered to persisted formats — useful, but no detail on pagination, ordering, or behavior when parameters are omitted.

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

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

Three short sentences, front-loaded with what is returned and what is excluded. The only wasted line is 'Read-only.', which restates an annotation verbatim.

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

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

An output schema exists so return structure needn't be explained, and the description still sketches the payload (layouts, variant metadata, primary format, available languages). Adequate for a zero-required-parameter read tool, with minor gaps around default behavior when language or variantId is omitted.

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 75% and the language, projectId and generationId descriptions are rich, so the schema does most of the work. The description reinforces that results are per-language and include variant metadata, but variantId remains undocumented in both places and no param syntax is added beyond the schema.

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

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

States a specific verb and resource ('Returns saved social-graphics layouts and variant metadata'), and scopes it to one language while naming the included fields (primary format, available languages). An agent can distinguish it from mutating siblings like save_graphics or render_graphics, though it never explicitly names get_graphics_format or list_variants as the alternatives.

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

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

Usage is only implied: 'saved' and 'Unsaved derived formats are absent' signal this reads persisted state rather than rendering. There is no explicit when-to-use or when-not-to-use guidance, and the routing hints (list_graphics_translations, translate_graphics) live in the schema's language description, not in the tool description.

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

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

Annotations confirm it is read-only and non-destructive. The description builds on this by detailing the specific operational logic of derived formats ('marked derived:true without persisting it'), adding behavior beyond the simple safety hints provided in 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 definition is concise and effectively front-loads the primary function into the first sentence. It is appropriately detailed without being verbose.

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 richness of the input schema and the existence of an output schema, the description fully answers the agent's need to know what data to expect and how the tool behaves with derived assets.

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 60% schema coverage, the description provides necessary semantic context by detailing exactly what is returned (layout, dimensions, read receipt) and listing specialized formats like 'App Store headers/search creatives,' linking the purpose back to specific input types.

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 its function: 'Returns one social or store-creative format layout, canvas dimensions and a same-target editing read receipt.' It clearly identifies the resources (layout, dimensions) and scope (social/store-creative formats).

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?

While it doesn't explicitly state 'when' to use it over siblings, it provides important functional guidance by explaining how it handles 'unsaved formats,' marking them as derived without persisting them, which is vital for agents distinguishing its behavior from saving/creation tools.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds useful behavioral context beyond annotations by disclosing plan-based history limits: 30 days on Free and 365 days on Unlimited. It repeats 'Read-only' but does not contradict annotations.

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

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

Three sentences, front-loaded with the core return value and optional competitor scope. The plan-limit sentence earns its place by communicating a real constraint, and the final 'Read-only' note is short despite duplicating an annotation.

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

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

The tool has an output schema for return shape and rich annotations for safety behavior. The input schema fully documents both parameters, and the description adds the important plan-based history-window constraint. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so both parameters are already well documented. The description adds limited semantic context by clarifying that appId is optionally for a competitor app, but it does not provide meaning beyond what the schema already supplies for trackedKeywordId.

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

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

The description states a specific verb and resource: returns rank history for one tracked keyword, optionally for a competitor app. This is clearly distinct from sibling list_keywords and list_keyword_competitors, which manage or list keywords rather than return historical rank data.

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

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

It gives clear context for when the tool applies: retrieving rank history for a single tracked keyword, with an optional competitor app. It does not explicitly name alternatives or when-not conditions, but the intended usage is unambiguous.

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

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

Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint=false), so the 'Read-only' sentence is largely redundant. However, the description adds genuine behavioral context beyond the annotations: main/mobile edits do not implicitly propagate to independent phone formats, and the response carries an editor link and an editing read receipt.

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

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

Three tight sentences, payload-first, with the propagation caveat placed where it matters. The trailing 'Read-only.' is redundant with annotations but costs only one clause.

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

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

An output schema exists, so the description needn't detail return values, and it still usefully names the notable ones. The remaining gap is that the editing workflow (omitting language lists translations only; re-call before transform_layout) is only discoverable in the schema, not the description.

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

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

No parameter is named or explained in the description; only 'one variant and language' hints at variantId and language. With 60% schema description coverage the schema does most of the work (language and generationId are well documented), so this lands at the baseline rather than being penalized.

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

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

States a specific verb and resource ('Returns saved screenshot layouts') and scopes it to one variant and language, enumerating the payload (phone-format layouts, editor link, editing read receipt). An agent can distinguish it from save_layout/sync_layout/transform_layout by the 'returns' framing, though no sibling is named explicitly.

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

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

Usage is only implied: 'Read-only' and the phone-format caveat suggest a retrieval step, but the description never says when to call it versus save_layout, sync_layout, or get_editing_reference, nor that language must be supplied before transform_layout. That key routing information lives only in the schema's language description.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so 'Read-only' in the description is pure repetition and earns no credit. The one genuinely new element, the 'same-target editing read receipt', is unexplained jargon — an agent cannot tell what it contains or why it matters — though the active-variant fallback behavior is useful context.

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

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

Three short sentences, front-loaded with the return content and ending with the safety flag; nothing is padded. The only blemish is the unexplained 'same-target editing read receipt' phrase, which spends words without transferring meaning.

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

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

With an output schema present the description needn't enumerate return fields, and annotations carry the safety profile, so what remains — which resource and which variant — is covered. The residual gap is routing between this tool and preview_mockup_animation / get_mockup_animation_export.

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

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

Schema coverage is 100% and the schema already documents the variantId omission behavior, so the description's restatement of it is duplicative rather than additive. It says nothing about the projectId/generationId alias pair, which is the one parameter relationship that actually needs narrative help.

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

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

States a specific verb ('Returns') and a specific resource ('saved mockup animation state') plus the resolved variant ID, which clearly separates it from create/update/preview/export siblings by implying retrieval of persisted state. It never names a sibling explicitly, so differentiation is inferred rather than 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?

'Omitting variantId reads the active variant' gives one concrete usage rule, but there is no guidance on when to choose this over preview_mockup_animation or get_mockup_animation_export, which are the obvious near-neighbors. Usage is implied by the read-only retrieval framing rather than spelled out.

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

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

Annotations already cover readOnlyHint/idempotentHint, so the redundant 'Read-only' adds nothing, but the description contributes real behavioral context: the download URL is short-lived and failed exports are refunded. Those are consequences an agent cannot get from the schema. It omits whether progress is a percentage or stage label.

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 outcome and the wait behavior, and every clause carries information except the trailing 'Read-only' which duplicates the 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?

An output schema exists, so return-value explanation is unnecessary, and the tool is a simple two-parameter read-only poll. The expiry-on-URL and refund-on-failure notes cover the non-obvious behaviors an agent needs before calling.

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 50%: waitSeconds is documented in the schema (including the maximum of 50) while exportJobId has no description anywhere. The description's 'bounded waitSeconds' is consistent but adds no detail beyond the schema, and it never explains that exportJobId comes from export_mockup_animation.

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

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

States a specific verb and resource ('Returns mockup export progress and a short-lived download URL when complete'), which clearly distinguishes this status-polling tool from export_mockup_animation (starts the job) and get_mockup_animation (returns the artifact). It stops short of explicitly naming those siblings, so an agent must infer the boundary from the verbs.

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

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

The polling intent is implied by 'progress ... when complete' and 'Supports a bounded waitSeconds', but the description never says when to call this versus get_mockup_animation or how often to retry. No exclusions or alternative-routing guidance are given.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the response contents (usage, limit, reset, a plan-management URL) and by explicitly ruling out mutations ('does not change the plan or purchase credits'), which prevents a plausible agent misread of a billing-adjacent tool.

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

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

A single dense sentence that front-loads the account-level data and then the project-scoped extension. Every clause earns its place, though the compound structure makes it slightly harder to parse than two shorter sentences would.

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

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

An output schema exists, so return values need detailed description only at a summary level, which the description provides. With one optional parameter and full annotation coverage, the agent has what it needs to call this correctly; only an explicit use-case cue 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 0%, so the description must carry the parameter's meaning, and it does: 'with a project ID, its keyword and competitor limits' explains both that projectId is optional and what it unlocks. It does not state the expected format (UUID) but the schema enforces that via pattern/format, so the gap is minor.

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

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

The description names a specific verb ('Returns') and enumerates the exact resources: API-export access, monthly export usage/limit/reset, and per-project keyword/competitor limits. An agent can tell precisely what comes back. It does not explicitly distinguish itself from get_capabilities, the only sibling with any conceptual overlap, so it stops short of a 5.

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

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

Usage is implied (check export quota/reset timing or project limits) but never stated as 'use this when X'. The closing clause 'Does not change the plan or purchase credits' establishes a useful negative boundary so the agent won't expect an upgrade path, but no alternative tool or prerequisite is named.

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 and openWorldHint=false, so the trailing 'Read-only.' merely restates structured data. The description does add useful behavioral context about the shape of the payload (variants, counts, links) and the projectId/generationId identity, but says nothing about failure modes or permissions, so it adds moderate value above the annotations.

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

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

Two compact sentences, front-loaded with the return contract, then the parameter alias note. The only wasted element is the trailing 'Read-only.' sentence, which duplicates the readOnlyHint annotation.

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

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

With an output schema present, the description need not explain return values, yet it still summarizes them helpfully, and it resolves the only ambiguity in the single input parameter. It lacks any guidance on when this read is appropriate versus sibling lookups, which is the one remaining gap for an otherwise simple, well-covered 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 0% for the single required parameter, so the description carries the burden — and it delivers a genuinely non-obvious fact: 'projectId and generationId identify the same project', meaning a generation ID value is acceptable even though no such parameter exists in the schema. It does not restate the UUID format, but that is already machine-readable in the schema.

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

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

The description gives a specific verb ('returns') and resource ('a project's ...') and enumerates exactly what comes back: app metadata, store-app identifiers, screenshot counts, content-type and active variants, dashboard/editor links. It implicitly separates itself from list_projects by operating on a single project, but never names a sibling tool explicitly, so it stops short of a 5.

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

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

There is no statement of when to call this rather than list_projects or get_store_listing/get_layout, and no preconditions or exclusions are given. The agent must infer usage purely from the returned-field list.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds genuinely useful output-behavior detail ('Transition names are normalized to content-motion semantics') and describes the read receipt, though 'Reading a translation does not change it' largely restates the readOnly hint.

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

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

Three tight sentences, front-loaded with what is returned. Some phrasing is jargon-heavy ('same-target editing read receipt', 'content-motion semantics') but each sentence carries content.

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

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

An output schema exists so return shape needn't be fully spelled out, and the safety profile is in annotations. However, for a 4-param tool with a rich set of promo-video siblings, the absence of any selection guidance leaves a real 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?

Schema description coverage is 75% and the schema itself documents language, projectId, and generationId with usage notes. The description adds no parameter-level meaning (e.g. nothing about variantId, the only undescribed param), so baseline 3 is appropriate.

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

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

The description uses a specific verb (Returns) and resource (saved promo-video configuration) and enumerates the payload (configuration, source/available languages, editing read receipt). It is clear what the tool does, but it does not distinguish itself from close siblings like get_promo_video_generation or preview_promo_video.

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

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

There is no explicit when-to-use or when-not guidance, and no mention of the obvious alternatives (get_promo_video_generation, preview_promo_video, get_promo_video_export). 'Reading a translation does not change it' implies a read context but doesn't route the agent between tools.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the closing 'Read-only' is redundant. Beyond that, the description genuinely adds behavior an agent cannot get from structured fields: URLs are short-lived and refreshable via re-read, and failed exports are automatically refunded, which informs retry decisions.

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

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

Three short sentences, front-loaded with the core action, then the two operational details that matter (URL expiry, refunds). No filler and nothing buried.

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

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

An output schema exists so return-field explanation is unnecessary, and the description covers the salient lifecycle states (completed/failed) plus refund behavior. The gap is the un-aided exportId parameter, which is the only thing an agent must supply.

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

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

The single parameter exportId has 0% schema description coverage — no description, no stated format intent beyond a uuid pattern. The tool description never mentions the identifier at all, so the agent gets no help on where the exportId comes from (presumably the export_promo_video response) or what happens on an unknown/stale id.

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

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

States a specific verb and resource: returns status and progress of a promo-video export. This is clearly distinguishable from the mutation siblings export_promo_video and generate_promo_video, though it never names them or the related get_promo_video / get_promo_video_generation readers, leaving the agent to infer which 'get' to call.

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

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

Implicit guidance is present — 'another status read can refresh the URL' tells the agent polling is the intended pattern. However there is no explicit statement of when to prefer this over get_promo_video or get_promo_video_generation, nor any note about how the exportId is obtained.

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=false and openWorldHint=false; the description's "Read-only; does not generate again..." largely restates that safety profile. It does add genuine value by naming the completed return payload (the prepared picker) and by ruling out apply/replace/export side effects, but says nothing about behavior for an unknown or failed job id, nor about polling cadence — the things an agent actually needs for a polling tool.

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

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

Two sentences, zero filler, with the positive statement of what is returned front-loaded ahead of the negative scope disambiguation. Every clause earns its place by either describing output or excluding a confusable sibling.

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 output schema exists, so the description doesn't owe the agent return-field documentation, and it correctly names the key payload (prepared picker). But with three undocumented parameters at 0% coverage and no guidance on polling vs. one-shot status checks, the definition is thin for a job-status tool with 3 required/optional params.

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

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

Schema description coverage is 0% and the description names no parameters at all. projectId and generationJobId are inferable from their names, but replaceVariantId on a declared read-only status call is genuinely puzzling and completely unexplained — an agent has no way to know when to pass it or what it changes about the response.

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

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

States a specific verb and resource: returns status of an existing promo-video preparation job, plus the prepared picker on completion. The closing clause names the four sibling operations it is NOT (generate, apply candidate, replace variant, export), so an agent can separate it from generate_promo_video, apply_promo_video_candidate, clear_promo_video and export_promo_video without opening any schema.

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

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

"of an existing ... job" and "when complete" make clear this is a status/poll call on a job id you already hold, and the exclusion list implicitly routes the agent to the mutation siblings. What's missing is explicit sequencing advice — nothing says to call generate_promo_video first, or whether to poll repeatedly until the picker appears.

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 repeats 'Read-only' but does add useful behavioral context by saying it returns status, progress, and available download artifacts; it does not discuss auth, rate limits, or polling 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 two short sentences with the core purpose front-loaded. 'Read-only' is redundant with annotations but does not create clutter significant enough to reduce conciseness.

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

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

For a simple single-parameter read-only getter with rich annotations and an output schema, the description is largely complete: it states the returned information and safety profile. The main remaining gap is that it does not explain how to obtain the renderId or whether callers should poll.

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

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

Schema description coverage is 0%, and the sole required parameter renderId is never named or explained in the description. The phrase 'existing screenshot render job' gives a broad sense of what the ID refers to, but not enough to compensate for the missing schema documentation.

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

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

The description names a specific verb and resource: it returns status, progress, and download artifacts for an existing screenshot render job. The word 'existing' distinguishes it from sibling creation tools like render_screenshots, and 'download artifacts' distinguishes it from list/view screenshot 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?

Usage is implied by 'existing screenshot render job': the agent should use it when it already has a render job to inspect. However, the description does not explicitly mention when to use this versus render_screenshots, list_screenshots, or view_screenshot, nor does it explain where the renderId comes from.

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 useful behavior beyond annotations by stating that it returns saved data and that asoCopy is null when none 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?

Two sentences, front-loaded with the primary return value and scope. The null-case detail is short and earns its place by setting expectations.

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

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

An output schema exists and annotations already cover safety, so the description does not need to explain return values or read-only behavior. It covers the core retrieval scope and null case, though parameter documentation remains thin.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies that variantId can specify a listing variant and that the active variant is used otherwise, but it does not explain projectId or the UUID expectations for either parameter.

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

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

The description uses a specific verb and resource: it returns saved App Store/Google Play listing copy, insights, and translations for the active or specified variant. The phrase 'Does not publish or modify store listings' clearly distinguishes it from generate_store_listing and update_store_listing.

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 signals retrieval of saved listing data and explicitly excludes publishing or modifying, which helps route the agent away from mutation siblings. However, it does not name alternatives such as generate_store_listing or update_store_listing or state exactly when each should be used.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description adds real value by scoping the returned content and warning that design/domain/publishing data is absent, but it says nothing about permissions, rate limits, or behavior when no website has been saved yet.

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 tight sentences with zero filler. The positive scope comes first and the negative scope second, which is the right order for an agent scanning for capability.

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

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

An output schema exists, so return values need no prose, and annotations cover safety and idempotency. For a two-parameter read tool the description supplies the content scope and the exclusion boundary — everything an agent needs to decide to call 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?

Schema description coverage is 0%, so the description carries the burden — and it only gestures at variantId via "for a variant", never mentioning projectId or that both are required UUIDs. The parameter names are largely self-explanatory and the UUID format is enforced in the schema, so the gap is modest rather than severe.

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

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

States a specific verb ("Read") and resource ("the saved website for a variant") and enumerates the payload scope: legal pages, links and SEO. The second sentence draws a boundary against dashboard-only concerns (design, domains, publishing), which lets an agent separate this from sibling tools like get_layout or save_website_pages without opening a schema.

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

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

Usage is implied by "saved website for a variant" and the note that design/domains/publishing live in the dashboard tells the agent what this tool will NOT return. However, no alternative tool is named for the excluded cases and no precondition (e.g., variant must already have a saved website) is stated.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=true and idempotentHint=false, so the safety profile is covered. The description adds real value beyond that: it states the return payload (relative path and photographer attribution) and that attribution is persisted into asset metadata, which is not derivable from annotations. It stops short of saying what happens on repeated imports or whether storage quota applies.

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

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

Three short sentences, front-loaded with the action and its scope, followed by the exclusion and one non-obvious behavioral fact. No filler and nothing repeated from the schema or annotations.

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

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

An output schema exists, so return values need not be spelled out, and the annotations cover the mutation profile. The description adds the key side effect (asset written to project storage, not applied to a design) and attribution persistence. The only real gap is the origin/format of importInput, which is left entirely to the schema.

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

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

Schema description coverage is only 33%, so the description needs to carry parameter meaning and does not. It never explains projectId, and it does not clarify that importInput is an opaque passthrough object taken verbatim from a search_stock_photos result — that critical detail lives only in the nested schema description. The mention of "Pexels or Unsplash" merely restates the provider enum.

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

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

States a specific verb and resource ("Imports a selected Pexels or Unsplash photo into project storage") and scopes it further by saying it "Does not apply the image to a design." It is clear what the tool does, though it never names the upstream sibling (search_stock_photos) that produces the importInput, so the differentiation is by scope rather than by sibling 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 exclusion "Does not apply the image to a design" gives one useful when-not signal, implying a separate apply/placement step. However, there is no positive routing guidance (e.g., "use after search_stock_photos" or "use upload_asset for local files"), so the agent must infer the workflow from the schema.

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 'Read-only' largely restates structured data. The genuinely additive piece is the caveat that folder names do not imply language — useful behavioral context — but nothing is said about pagination/offset behavior or the shape of results.

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

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

Three short sentences, front-loaded with the core action and ending on the constraint. 'Read-only' is the only sentence that does little work given the 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?

An output schema exists so return values need no explanation, and annotations cover the safety profile. However, with zero schema description coverage on projectId and offset, an agent gets no help on the pagination parameter from any source.

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

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

Schema description coverage is 0% for 2 parameters, so the description needed to carry the burden and does not: projectId is never mentioned and the offset parameter's pagination role is unstated. Only the abstract notion of device/platform/locale bindings hints at what is being filtered.

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 (Lists) plus resource (screenshot folders) with a qualifier about bindings. It implicitly differentiates from the create/rename/delete asset folder siblings, though it never names them or contrasts scope.

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?

Usage is only implied by the verb; there is no statement of when to call this versus list_assets, list_screenshots or the other folder siblings, and no prerequisites (e.g. project membership) are mentioned.

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

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

Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint=false), but the description adds non-obvious behavior the annotations cannot: results contain relative storage paths, signed preview links stay private widget data, and each folder is capped at its newest 100 files with truncation reported. That truncation cap is exactly the kind of limit an agent needs before assuming completeness of results. It does not describe pagination or how to retrieve files beyond the 100 cap.

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

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

Three tight sentences with the resource enumeration front-loaded, followed by the read/write distinction, then the return-shape and truncation caveats. No filler. The 'Upload is an explicit widget action' clause is slightly oblique but earns its place by preempting a read/write confusion.

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

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

An output schema exists, so return structure need not be explained, yet the description still adds useful return semantics (relative paths, private signed links) plus the 100-file-per-folder truncation rule. Combined with annotations covering safety and idempotency, an agent has enough to call this correctly. The only real gap is disambiguation from the many sibling list_* tools.

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

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

Schema description coverage is 0%, so the description must compensate and it largely does not — projectId is never mentioned, though 'a project's screenshots' implies project scoping. The schema itself supplies the uuid format and pattern, which limits the damage. With a single required parameter, an agent can still call this correctly, so 3 rather than lower.

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

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

States a specific verb (Returns/List) and enumerates the resource precisely: screenshots, illustrations, icons, backgrounds, panoramas, recordings, music, clips and fonts, scoped to a project. An agent can tell this is the broad project asset library rather than a single-type list. It stops short of naming the overlapping siblings (list_screenshots, list_illustrations, list_fonts, list_asset_folders), so the boundary is inferred rather than declared.

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?

'Listing is read-only; Upload is an explicit widget action' clarifies the read/write split versus upload_asset, but only obliquely. There is no explicit statement of when to call this versus list_screenshots, list_illustrations, list_fonts or list_asset_folders, which are the real ambiguity for an agent given the large sibling set. Usage is implied by the enumerated asset types rather than guided.

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=false and openWorldHint=false, so the trailing 'Read-only.' restates structured data rather than adding to it. The only added value is disclosing what categories of data the response contains, which is partially redundant with the output schema.

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

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

Single front-loaded sentence that leads with the verb and the resource, followed by a short qualifier. The 'Read-only.' fragment is the one sentence that does not earn its place, since annotations cover it.

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?

Zero-parameter tool with an output schema and rich annotations; the description covers the domain of results well enough that an agent knows exactly what it is asking for. Nothing needed to invoke it correctly is missing.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing parameter-wise the description could clarify that the empty schema does not. No incorrect or missing parameter discussion.

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

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

States a specific verb ('Lists') and resource ('screenshot export formats'), then enumerates the exact facets returned (device families, platforms, authored dimensions, resolution presets). This is far more concrete than a sibling like get_capabilities, though it never names which sibling it complements.

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

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

No explicit when-to-use or when-not-to-use statement, and no prerequisite framing such as 'call before render_screenshots to discover valid dimensions'. Usage is only implied by the enumerable contents, so an agent must infer that this is a discovery/reference call.

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/openWorldHint, so the trailing 'Read-only' earns no credit. The description does add genuinely useful context — that results include weights per family and that names are validated against layout rules — but says nothing about result volume, pagination, or how `limit` behaves.

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

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

Three compact sentences: what it returns, why the names matter, and safety. Front-loaded and free of filler.

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