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

Annotations already declare idempotentHint=true and destructiveHint=false, but the description adds substantive context beyond them: it is a reversible state transition via restore_brand, styling tokens are preserved, and existing slideshow runs referencing the brand keep working. Those side-effect disclosures are exactly what an agent cannot infer from annotations alone.

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

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

Front-loads the core action and its scope, then layers the exclusion, reversibility, side effects, and return value in tight, non-redundant sentences. Every 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?

An output schema exists, so the return value need not be elaborated, and the description nonetheless notes the returned Brand's archived status. With usage alternatives, side effects, and reversibility all covered, the definition is complete for a single-parameter state-transition 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?

There is one parameter with 100% schema description coverage, so the schema fully documents brandId. The description adds no format or syntax detail beyond it, making the baseline 3 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+resource ('Archive an active Brand') and immediately scopes the effect ('soft-hide it from default pickers and list queries without losing styling tokens'). This is clearly distinguishable from sibling delete_brand and restore_brand 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?

Explicitly states when to use it ('Call to declutter workspace brands') and when not to, naming the alternative ('Do NOT use for permanent deletion; use delete_brand instead'). Nothing about tool selection is left to inference.

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

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

Annotations already declare non-destructive, idempotent, non-readOnly, but the description adds substantial context beyond them: binaries are retained in storage, the change is fully reversible via restore_image, and referencing slides/carousels keep rendering uninterrupted. That dependency-impact disclosure is exactly what an agent needs before mutating shared content.

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?

Front-loads the core action and its key constraint, then adds alternatives and side effects in descending priority. It runs slightly long at five sentences, and the return-value sentence is partly redundant with the output schema, but no sentence is 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 single-param state-transition tool with an output schema present, the description covers action, scope, reversibility, side effects on dependents, and the deletion alternative. An agent has everything needed to call it correctly and anticipate consequences.

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 single parameter (imageId) is fully documented in the schema, so the description adds nothing parameter-specific. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb+resource ('Archive an image asset') and immediately scopes it against the binary-preserving behavior ('soft-hide it from active media pickers without deleting binary files'). It explicitly names the sibling tools delete_image and restore_image, so an agent can route correctly without reading other 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?

Gives the triggering condition ('Call to declutter media library when an image is retired from active use') and an explicit alternative with its own condition ('For permanent deletion, use delete_image instead'). This is textbook when-to-use / when-not-to-use guidance.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, but the description adds substantial context beyond them: soft-hide semantics, preservation of slide records, rendered assets, and external links, full reversibility via restore_slideshow_run, and the resulting status change to archived. This is rich behavioral disclosure 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?

The description is front-loaded with the core soft-hide behavior, then adds usage guidance, exclusion guidance, reversibility, preservation guarantees, and return status. Each sentence is short and contributes distinct information without restating the tool name or schema.

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 annotations, a fully covered input schema, an existing output schema, and sibling tools, the description supplies everything needed: what is hidden, what is preserved, when to use it, when not to use it, the alternative destructive sibling, reversibility, and the resulting status.

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

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

Schema description coverage is 100% and the single required parameter runId is fully documented in the schema. The description adds no additional syntax, formatting, or validation detail for runId, so the baseline of 3 is appropriate when the schema carries the parameter semantics.

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

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

The description states a specific verb+resource ('Soft-hide an active Slideshow Run') and immediately bounds it against deletion ('without deleting slide data or review URLs'). It explicitly distinguishes the operation from delete_slideshow_run, so an agent can route correctly without opening 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?

It gives explicit when-to-use ('Use to declutter the workspace after campaign completion'), when-not-to-use ('Do NOT use for permanent destruction'), and the correct alternative for destruction ('use delete_slideshow_run instead'). It also names the reversal path via restore_slideshow_run.

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 the safety profile (non-read-only, idempotent, non-destructive), but the description adds substantial context beyond them: workspace owner authorization requirement, a permanent audit log record, immutability, and re-attestation semantics that preserve prior history. These are exactly the traits an agent needs before invoking a compliance write.

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?

Front-loaded with the core purpose, then usage, exclusions, authorization, and mutation semantics in order of importance. Dense but every sentence carries distinct information; nothing is padding.

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 (the closing 'Returns attestation confirmation object' is harmless redundancy). With authorization, permanence, idempotent re-attestation behavior, and routing all covered, nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description goes further by explaining statementVersion semantics — that a new version creates a new timestamped record without revoking prior history — which is meaning beyond the schema's brief field note.

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 ('Record an immutable legal copyright or commercial rights ownership attestation for an image asset') and explicitly distinguishes itself from siblings update_image and import_image. An agent can identify the operation and its scope without opening the 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?

Gives explicit when-to-use ('Call before multi-platform export to satisfy commercial compliance requirements'), when-not-to-use with named alternatives (update_image for metadata, import_image for uploads), and an exclusion ('Not required for personal or draft-only runs'). This is close to ideal routing guidance.

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

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

Annotations already declare the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), and the description goes further by disclosing the owner-authorization requirement, that the initial record is persisted at revision 1, and what the created entity returns. It adds real behavioral context rather than restating 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?

Five short sentences, front-loaded with purpose and followed by sequencing, exclusion, and preconditions in priority order. Each sentence earns its place, though the return-value sentence is somewhat redundant given an output schema exists.

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

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

For a mutation tool with nested-object parameters and an output schema, the description covers purpose, sequencing, exclusion, authorization, and persistence semantics. An agent has everything needed to call it correctly without consulting siblings.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema; the baseline is 3. The description restates the categories of fields (typography, colors, handle, optional logo) without adding format, constraint, or default details beyond what the schema provides.

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

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

States a specific verb and resource ("Create a new owner-scoped Brand kit") and enumerates what the entity defines (typography, color palette, handle, optional logo asset). This is easily distinguished from update_brand, delete_brand, and the other brand siblings.

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

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

Gives explicit sequencing guidance ("Call before creating slideshow runs to establish consistent visual identity"), an explicit exclusion with the correct alternative ("Do NOT use to edit an existing brand; use update_brand instead"), and a precondition (workspace owner authorization). Nothing is left to inference.

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

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

Annotations already declare readOnly=false, idempotent=false, and destructive=false, so the write/safety profile is covered. The description adds real value beyond that: it flags the durable nature, states the 'workspace owner write authorization' requirement, and describes the returned artifacts. It stops short of noting rate limits or failure modes, so it lands at 4 rather than 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?

Front-loaded with the core action and input, followed by prerequisite, exclusion, auth, and return value in a compact block. Every clause earns its place, though the return-value sentence is slightly redundant given an output schema exists.

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

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

For a mutation tool with a nested ContentPack input, the definition covers purpose, prerequisite, exclusion, authorization, and the resulting record. Since an output schema exists, the return description is a bonus rather than a gap, leaving nothing an agent needs missing.

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

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

Schema coverage is 100%, so the schema already documents all four parameters, establishing a baseline of 3. The description reinforces the structure of the required 'pack' (platform, pages array with bound templateId and slot text values) but adds little beyond the schema and never mentions the optional brandId/contentSlug/brandProfileId parameters.

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

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

States a specific verb and resource ('Create a durable multi-page Slideshow Run from a structured ContentPack') and clarifies the input contract. It explicitly distinguishes itself from update_slideshow_run, so an agent can tell the two apart without opening schemas.

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

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

Gives an explicit prerequisite ('Call recommend_slideshow_templates first') and an explicit exclusion ('Do NOT use to edit an existing run (use update_slideshow_run instead)'). The alternative is named with the condition that selects it.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), so the description only needs to add context. It does: 'Requires workspace owner authorization' is a real precondition not present in structured fields, and it discloses the created record shape and the interactive authoringStudioUrl side effect. It does not, however, note the non-idempotent duplicate-creation behavior beyond what the annotation implies.

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

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

Four sentences ordered purpose → usage → exclusions → auth → return, each carrying distinct information with no repetition. Nothing is padded and the purpose is front-loaded.

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

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

For a non-idempotent creation tool with nested object params, full schema coverage, and an output schema, the description covers the missing pieces: the authorization requirement and the side effect of producing an authoring URL. An agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description only loosely gestures at them ('custom layout, layers, and slot contracts') and adds no format or syntax guidance beyond what the schema provides. 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+resource ('Initialize a new Page Template draft for authoring') and scopes it with the concrete features (custom layout, layers, slot contracts). It explicitly distinguishes itself from update_template_draft and list_templates, so an agent can route correctly 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?

Gives an explicit trigger ('when authoring a new slide template from scratch') plus two named exclusions with the sibling to use instead ('Do NOT use to edit... use update_template_draft', 'browse public templates... use list_templates'). This is the full when/when-not/alternative pattern.

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 the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description adds the key trait the annotations cannot convey: the operation is asynchronous and produces a render job rather than a synchronous image. It omits how the job completes or is polled, but output schema exists to cover the result shape.

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

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

Two sentences, both front-loaded and purposeful: the first defines the action and output, the second routes to the alternative. No filler or redundancy.

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

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

For a one-parameter job-creation tool with annotations and an output schema, the description covers purpose, async nature, and the alternative path. The only gap is guidance on how/when to poll or retrieve the finished preview, which the output schema may partially address.

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

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

Single parameter with 100% schema description coverage, so the schema fully documents draftId. The description only restates that the render targets a template draft, adding no syntax or format detail beyond the schema. 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: 'request an asynchronous server-side render preview image of a template draft for thumbnail generation.' The scope (draft -> preview image, for thumbnails) is unambiguous, and no sibling tool covers preview rendering.

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

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

Explicitly names the alternative path ('For interactive real-time visual authoring, prefer opening the authoringStudioUrl in browser'), which tells the agent when NOT to use this tool. It stops short of stating when this job-based tool is the right choice versus any other rendering route, but the exclusion is clear.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds important nuance beyond them: the delete is a move to trash (not necessarily permanent purge), it requires explicit confirmation, and dependent design workflows may lose default brand styling. These downstream effects and the confirmation requirement are real behavioral context.

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

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

Five short sentences, each earning its place: purpose, usage constraint, alternative, destructive warning, and return note are front-loaded in that priority order with zero 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 no explanation, yet the description still notes the confirmation record. Combined with usage guidance, alternatives, and downstream-effect warnings, an agent has everything needed to call this destructive tool correctly.

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

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

Schema description coverage is 100% and the single brandId parameter is fully documented in the schema. The description adds no syntax, format, or sourcing detail beyond what the schema already provides, so the 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 ('Move a Brand to trash for deletion') and explicitly distinguishes itself from the sibling archive_brand. An agent can identify the operation and its scope without opening the 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?

Gives an explicit when-to-use condition ('only when a brand kit is obsolete and permanently discarded') and names the alternative (archive_brand) with the exact condition that selects it ('if existing runs still use this brand theme'). Nothing is left to inference.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description goes further: it requires explicit user confirmation, warns that active slide bindings may cause render failures, and notes it returns a confirmation record. These are real behavioral consequences beyond the annotation flags.

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

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

Five short sentences, front-loaded with the action and then the guards and risks in descending priority. Every sentence carries information; it is slightly dense but nothing is redundant.

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. The description covers purpose, preconditions, the safer alternative, confirmation requirement, and failure risk – everything an agent needs before invoking a destructive single-parameter tool.

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

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

Schema description coverage is 100% and there is only one parameter, so the schema fully documents imageId. The description adds the useful nuance that imageId may be bound to active slides, but this is a consequence rather than parameter syntax, so the 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 ('Move an image asset to trash for permanent removal') and immediately distinguishes itself from the sibling archive_image, which the agent would otherwise confuse it with. The 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?

Gives explicit when-to-use conditions ('obsolete, copyrighted without license, or marked for permanent deletion') and an explicit alternative with its selecting condition ('If existing slides still use this image, prefer archive_image to hide it safely'). This is textbook routing guidance.

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

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

The annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds substantial context beyond them: cascade deletion of slide page records, invalidation of studio review URLs, the requirement for explicit user confirmation, and the return value. These are concrete consequences an agent needs before invoking a destructive 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?

Five short sentences, each carrying a distinct payload (action, condition, alternative, consequences, return), with the destructive nature and the routing decision front-loaded. Nothing is padding.

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, yet the description still notes the deletion confirmation record, and it covers the destructive semantics, cascade effects, and sibling routing. Nothing an agent needs to call this safely 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% and there is a single required runId, so the schema already carries the parameter burden and the baseline is 3. The description adds no parameter-level detail; if anything, the opening phrase 'Move a Slideshow Run to trash or permanently remove it' implies a soft-vs-hard delete choice that no parameter exposes, which could mildly mislead.

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 (delete/permanently remove) and resource (Slideshow Run), plus the scope of collateral deletion (slide page records). It explicitly distinguishes itself from the sibling archive_slideshow_run, so an agent can route correctly without opening either 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?

It gives an explicit when-not condition ('Use only when a run is obsolete and permanently discarded') and names the concrete alternative (archive_slideshow_run) with the exact scenario that selects it (preserving review links and data). This is about as complete as usage guidance gets.

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 readOnlyHint=false, so the agent knows this is destructive. The description adds valuable behavioral context beyond annotations: it specifies exactly what is destroyed ('draft canvas data, layer AST, and unpublished revisions cannot be recovered') and states the auth requirement ('requiring explicit user confirmation'). It doesn't cover rate limits or return record shape, but with annotations covering the safety profile, this is strong.

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

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

Four sentences, each earning its place: purpose, when to use, when-not with alternative, destruction details, and return value. Front-loaded with the operation and resource, then the constraint, then consequences. Zero waste.

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

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

Given destructiveHint=true annotations, an output schema already present, and 100% schema coverage for the single parameter, the description is complete. It covers purpose, when/when-not, irreversibility, confirmation requirement, and the return record, leaving nothing an agent needs to call this correctly.

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

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

Schema coverage is 100%, so the schema already documents the single draftId parameter. The description adds only the confirmation that draftId identifies what is 'permanently deleted', which is marginal beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting for a one-parameter tool.

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

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

The description states a specific verb ('permanently delete') and resource ('template authoring draft by draftId'), and explicitly distinguishes itself from the sibling publish_template_draft by naming it and describing when to use each. An agent can tell this apart from all other draft tools (get, update, create) 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?

The description gives explicit when-to-use ('Call only when abandoning a draft that should be permanently destroyed') and when-not ('If the draft is complete and ready for production, call publish_template_draft instead'), naming the alternative tool by name. Nothing is left to inference.

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

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

Annotations already cover readOnlyHint, idempotentHint, destructiveHint, and openWorldHint. The description adds the workspace-owner scoping constraint and the workflow purpose (capture baseRevision before mutation), which is valuable beyond the annotations, though it doesn't discuss error cases for stale revision.

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?

Front-loads the fetch purpose and return contents, then adds the workflow hook and alternative. Slightly dense but 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?

With an output schema present, return-value detail is not required, yet the description still summarizes key fields. Combined with annotations and the workflow guidance, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100% and the single brandId parameter is already documented. The description repeats 'by brandId' without adding format or sourcing detail beyond what list_brands provides. Baseline 3 applies when schema does the heavy lifting.

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

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

States a specific verb+resource (fetch a Brand profile by brandId) and enumerates the returned contents (typography tokens, 4-color palette, logoAssetId, baseRevision). Clearly distinguished from siblings like list_brands and update_brand.

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

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

Explicitly says to call it before generating or updating branded slides to inject brand styles and capture baseRevision, and names list_brands as the alternative for discovering brandIds. When-to-use is fully specified.

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 agent knows the safety profile without prose. The description adds a useful behavioral framing ('Read-only platform catalog lookup') but does not go beyond the annotations in any material way, and with an output schema present, return-shape detail is not required here.

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?

Front-loaded with purpose, then sequencing, then alternatives, then a behavioral note. Slightly over-stuffed for a one-parameter lookup, and the closing 'Returns full gradient recipe object' restates the opener, but nothing is misleading or wasteful enough to penalize heavily.

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

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

For a single-id read tool with full schema coverage, annotations covering safety, and an output schema covering returns, the description covers purpose, sequencing and alternatives adequately. The only minor gap is that it does not state what happens when gradientId is unknown, though that is a low-stakes 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 100% and the single gradientId parameter already carries a format example (grad_warm_sunset). The description adds no syntax or constraint detail beyond what the schema provides, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb (Retrieve) and resource (full gradient CSS recipe) scoped by gradientId, and enumerates what the recipe contains (linear angle, color stops, semantic token values). It explicitly distinguishes itself from list_gradients, so an agent can tell the two apart without opening schemas.

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

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

Gives the sequencing rule ('Call after list_gradients') and the purpose ('to materialize background styles or decorative surfaces on cards'), then names the alternative by tool name. Both when-to-use and the sibling route are 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?

The description asserts 'Idempotent: repeated calls with identical keys return the existing asset without consuming extra quota', but the annotations declare idempotentHint=false for the same operation. Identical arguments (the required idempotencyKey is part of the arguments) producing no additional effect is precisely the MCP meaning of idempotent, so the description directly contradicts the structured hint. This is a serious inconsistency an agent could rely on incorrectly.

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: purpose first, then workflow, then idempotency/quota behavior, then return shape. Nothing is bloated, though the final sentence enumerating return fields ('SVG string, iconAssetId, contentHash') is partly redundant given an output schema exists.

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

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

For a two-parameter tool with a full output schema, the description covers purpose, prerequisite workflow, and the dedup/quota behavior an agent needs. The enumerated return values duplicate the output schema, and the idempotency claim conflicts with the annotations, which is the one substantive 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 100%, and both parameters are documented in the schema itself, so the baseline is 3. The description restates the purpose of idempotencyKey ('to prevent duplicate creation') and qualifies iconId as 'confirmed', but adds no syntax, format, or behavioral detail beyond what the schema already supplies.

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

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

The description states a specific verb+resource ('Materialize an immutable TemplateIconAsset ... from a confirmed iconId'), which correctly clarifies that the misleadingly named 'get_icon' actually creates/returns an asset. It explicitly positions itself against the sibling 'search_icons' (confirm a candidate first, then materialize), so an agent can distinguish the two without opening schemas.

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

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

It gives a clear workflow precondition: 'Call after confirming a candidate from search_icons', which names the alternative tool and the sequencing condition. It lacks explicit when-not conditions or error guidance, so it stops short of a full 5, but the usage context 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 declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world, so the safety profile is covered. The description adds genuinely new context (workspace-owner scoping, that the URL is public R2/CDN delivery), though 'Read-only query' largely restates the annotation. With annotations carrying the load, this is adequate rather than rich.

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?

Front-loads the core action and output, then usage, then alternatives, then scope in a compact block. Every sentence carries distinct information (purpose, inspection target, alternative sibling, scope) with 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?

All parameters are documented, annotations cover the safety profile, and an output schema exists so return-shape detail is not required. The brief mention of returning the 'full Image entity' plus scoping notes make it complete enough for a single-ID lookup, with only marginal room to elaborate on auth or error cases.

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, and the schema's description for imageId ('The unique image asset identifier to retrieve.') already has 100% coverage. The description confirms retrieval is keyed 'by imageId' but adds no format, source, or constraint detail beyond the schema, matching the baseline for fully covered schemas.

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 (fetch) and resource (image asset metadata + public R2/CDN delivery URL) tied to an imageId. It explicitly distinguishes itself from the sibling list_images, so an agent can route correctly without opening either 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?

Gives a concrete use case ('inspect dimensions, content hash, and rightsStatus before binding to slide slots') and names the alternative ('Use list_images to search assets across media library'). It stops short of stating explicit when-not-to-use conditions or other near-neighbors like get_icon/get_gradient, but the routing intent is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds genuine context beyond them: the concurrency-locking role of baseRevision and the fact that reads are scoped to the authenticated workspace owner. It stops short of describing pagination or size limits, which is a minor gap given an output schema 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?

Three sentences, zero filler: purpose first, then the sequencing requirement, then the alternative. The most actionable constraint (call before update) is front-loaded after the purpose statement.

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 documented, yet the description still signals what the payload contains. Combined with explicit usage sequencing and auth scoping, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100% for the single runId parameter, so the schema already documents it fully. The description adds only the framing 'by runId' plus the note that list_slideshow_runs is how you obtain one, which is routing rather than parameter syntax. 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 (Retrieve) and resource (Slideshow Run by runId) and enumerates the returned payload (slide pages, template IDs, slot contents, brand theme snapshot, revision number, review URL). This clearly distinguishes it from list_slideshow_runs, update_slideshow_run, and the template/image siblings.

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

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

Gives an explicit when-to-use condition ('Call before update_slideshow_run to inspect current slide contents and capture baseRevision for concurrency locking') and names the alternative for discovery ('Use list_slideshow_runs to discover runIds'). Nothing about selection is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered structurally. The description adds real value beyond that by disclosing what the payload contains (the public slots[] table with key, type, required, constraints) and restating the read-only catalog nature.

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

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

Three sentences, no filler, and the core purpose and return content are front-loaded before the alternatives clause. Slightly dense with parenthetical detail but nothing is wasted.

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 documentation is not strictly required, yet the description still signals the slots structure and its binding use case. Combined with full annotation coverage, an agent has everything needed to call it correctly.

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

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

Only one parameter with 100% schema description coverage ('The unique published template identifier to retrieve.'), so the schema carries the semantics. The description adds nothing about the identifier's format or where to obtain it, which is the baseline-3 case.

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 ('Get one published template detail') and immediately scopes the return to the public slots[] table. The 'published' qualifier separates it from get_template_draft and list_template_drafts in the sibling set.

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 concrete downstream usage ('Use slots to bind slide copy in create_slideshow_run or inspect template constraints') and names an alternative ('Use list_templates to browse catalog'). It does not clarify when to prefer this over get_template_draft, but the browse-vs-fetch distinction is 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 nevertheless adds real context: the operation is a read-only query scoped to the draft owner (an auth/scoping constraint not in annotations) and previews the payload shape. It doesn't discuss pagination or response size, but for a single-entity fetch that is minor.

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 with no filler; purpose, prerequisites, and alternatives are ordered by importance. Enumerating the returned fields is slightly redundant given an output schema exists, which keeps it from a 5.

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

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

For a single-param read tool with full schema coverage, annotations, and an output schema, the description supplies everything else needed: usage sequencing, alternatives, ownership scoping, and a summary of returned entity content.

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 a single required parameter at 100% schema description coverage, the schema fully documents draftId. The description only restates that retrieval is keyed by draftId, adding no format, sourcing, or constraint detail beyond the schema, so the 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 (fetch authoring draft details by draftId) and enumerates the exact content retrieved: layer AST, slot contracts, theme bindings, validation logs. This clearly separates it from list_template_drafts, update_template_draft, and publish_template_draft.

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

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

Explicitly says to call it before update_template_draft or publish_template_draft to inspect structure and check validation status, and names list_template_drafts as the discovery alternative. When-to-use and alternatives are both 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 declare the safety profile (readOnly false, destructive false, idempotent false). The description adds real behavioral context: the asset is stored on Cloudflare R2 with metadata registered in Directus, write permissions are needed, and it returns a created record with imageId and a public delivery URL. The only gap is that it never addresses idempotency/duplicate handling despite idempotentHint=false.

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

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

Four tight sentences, front-loaded with the core action, then usage, then exclusion, then requirement. Every sentence adds distinct information with 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?

With annotations, a fully-described 5-param schema, and an output schema present, the description covers everything an agent needs: what it does, when to use it, the sibling alternative, the permission requirement, and the storage/return behavior.

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

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

Schema description coverage is 100%, so all five parameters are already documented in the schema. The description adds no extra syntax, format, or defaulting guidance for file/name/filename/sourceUrl/rightsStatus beyond what structured data provides, which is the baseline 3.

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

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

Specific verb+resource: 'Upload a new image file into the permanent workspace media library', and it distinguishes itself from import_template_image by name. An agent can tell it apart from the other image siblings without reading 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?

Explicit when-to-use ('add reusable media assets for slideshow runs and brands') and an explicit when-not with the alternative ('Do NOT use for transient template draft canvas images (use import_template_image instead)'). It also states the permission prerequisite ('Requires workspace write permissions').

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

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

The description asserts 'Idempotent: duplicate uploads with identical idempotencyKey return the existing asset,' but the annotations declare idempotentHint=false. Since idempotencyKey is a required argument, every call includes it, so the stated behavior directly contradicts the annotation. This is an annotation contradiction, which per the rubric scores 1 regardless of the otherwise useful auth and return-value details.

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

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

Purpose is front-loaded and each sentence carries distinct information (scope, when-to-use, exclusion, auth/idempotency, return shape). The final sentence describing returned fields is partly redundant given the tool already has an output schema, so it is slightly over-long rather than wasteful.

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

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

For a 13-parameter mutation tool with a full output schema and annotation coverage, the description supplies the missing routing, authorization and return-shape context. The only shortfall is that its idempotency claim conflicts with idempotentHint=false, leaving the true retry behavior ambiguous.

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% across all 13 parameters, so the schema already documents draftId, provider, rightsStatus, mimeType, etc. The description only re-references idempotencyKey and mentions auth; it adds no syntax or format detail beyond the structured fields. 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 (import/upload), a specific resource (transient image asset) and its scope (attached to a template draft canvas). It explicitly distinguishes itself from the sibling import_image, so an agent can disambiguate without opening either 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?

Gives both sides: 'Call while authoring a template draft in canvas studio' and an explicit exclusion ('Do NOT use for general workspace media library assets, logos, and photos (use import_image instead)'). The alternative tool is named with the condition that selects it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the meaningful scoping detail that results are limited to the current workspace owner, though 'read-only query' largely restates the annotation.

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 compact sentences, front-loaded with the what and the when, with no filler. The closing 'Returns array of Brand summaries' is mildly redundant given an output schema exists, keeping it just short of a 5.

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

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

For a zero-parameter read-only list tool with full annotation coverage and an output schema, the description covers purpose, usage trigger, alternative, and scoping. Nothing an agent needs to select or 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 no parameters (0 params, empty schema), so there is no parameter semantics to explain; baseline for a parameterless tool is 4.

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

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

States a specific verb and resource ('List owner-scoped Brands') plus the payload contents (typography tokens, color palettes, logos). It is immediately distinguishable from the sibling get_brand, which the description names 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?

Gives an explicit trigger ('Call to discover available brand identities before creating or styling slideshow runs') and names the alternative tool with the condition that selects it ('Use get_brand when you have a specific brandId'). Nothing is left to inference.

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

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

Annotations already cover readOnly/idempotent/non-destructive/openWorld=false, so 'Read-only platform catalog query' is largely redundant. The description does add real behavioral context beyond the annotations: results are summaries rather than full recipes, and full CSS requires the sibling get_gradient call. No permissions, pagination, or error behavior is described.

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

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

Three short sentences with zero filler, front-loaded with the action and scope, then the use case, then the sibling routing. Every 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?

For a read-only catalog list with full annotation coverage, a complete 100%-described schema, and an output schema, the description supplies everything the agent needs: what it returns (summaries), when to call it, and where to go for full detail.

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 q, tag, and limit are already fully documented in the schema. The description only restates the query/tag concepts and adds no syntax, matching rules, or limit guidance beyond what the schema provides, so the 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 ('list or search') plus resource ('platform gradient recipe summaries') and the narrowing fields (keyword query or tag). It also names the sibling get_gradient as a distinct operation, so an agent can separate the two without opening either 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?

Gives an explicit trigger ('Call to discover gradient presets before styling cards') and an explicit alternative with its condition ('Use get_gradient to retrieve full CSS declaration for a specific gradientId'). Nothing about when-to-use is left to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and non-open-world, so the safety profile is covered. The description adds genuinely useful context beyond that: the owner/workspace scoping and that results feed slot assignment. It does not mention pagination or result limits, which is a minor 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?

Front-loads the core action and scope, then covers returns, usage, alternatives, and safety in order. Slightly redundant in mentioning slot context twice ('for slot assignment' and 'before slot binding'), but overall efficient.

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

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

With an output schema present and rich annotations, the description needs only to cover scope, usage, and routing. It does all three, so an agent has everything required to select and invoke it correctly.

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

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

Schema coverage is 100% and the single parameter q is already documented in the schema as a search term matching name or provenance source. The description only restates it as an 'optional search query q' without adding syntax or matching behavior, so the 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 ('List owner-scoped image assets in the media library') and names the scope ('scoped to workspace owner'). It clearly distinguishes itself from get_image, the sibling that handles single-image retrieval.

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

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

Explicitly states when to use it ('browse media assets or discover imageId before slot binding') and names the alternative with its selecting condition ('Use get_image to fetch full metadata for a specific imageId'). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful non-annotation context: the result set is scoped to the authenticated workspace owner, and it enumerates the returned fields (metadata, platform target, page counts, revision numbers, timestamps). It stops short of pagination/limit behavior, keeping it just under a 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?

Front-loaded with the core action, then labeled 'Alternatives:' and 'Behavior:' segments that make scanning easy. Every sentence carries distinct information with no redundancy.

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

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

An output schema exists, so return values needn't be spelled out, yet the description still names the key fields. Combined with clear usage routing and safety context, nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so all seven filters are already documented in the schema, and the description only summarizes three of them (platform, status, query). Baseline 3 is correct since the schema does the heavy lifting and the description adds no syntax or format detail beyond it.

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

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

States a specific verb and resource ('List owner-scoped Slideshow Runs') with the scoping constraint and filter categories front-loaded. It explicitly distinguishes itself from get_slideshow_run, so an agent can tell them apart without opening either 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?

Names concrete use cases ('browse existing carousels or find a runId before inspection, updating, or archiving') and an explicit alternative with its selecting condition ('Use get_slideshow_run when you already have a specific runId'). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and closed-world scope. The description adds value beyond that by specifying the account-owner scoping and previewing the returned summary fields (validation status, name, timestamps). It does not cover pagination or ordering behavior, which would be the remaining useful detail for a list 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?

Four sentences, each earning its place, with the core action front-loaded. The trailing 'Read-only query scoped to account owner' partially restates the readOnlyHint annotation, but the account-owner scoping is new information, so the redundancy is minor.

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

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

For a zero-parameter, read-only list tool with full annotation coverage and an output schema, the description covers everything an agent needs: what is returned, why to call it, and which sibling to prefer when a draftId is known. Return-value details are appropriately left to the output schema.

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

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

The tool takes zero parameters, so there is no parameter semantics to document and the baseline of 4 applies. The description correctly does not invent filtering options that the empty schema cannot support.

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 ('List all template authoring drafts') and immediately narrows scope to 'the current account owner'. It distinguishes itself from the sibling get_template_draft by explicitly calling out that the latter is for a known draftId and returns the full layer AST.

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 two concrete use cases ('resume an authoring session' and 'discover draft IDs before updating or publishing') and names the alternative tool plus the condition that selects it. An agent can route between list and get without opening either 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=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered; the closing 'Read-only catalog query' largely repeats that. The one genuinely additive behavioral signal is that returns are 'summaries', implying detail must come from get_template, but no pagination or result-size behavior is described.

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

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

Three short sentences, front-loaded with the verb and resource, then routing. The trailing 'Read-only catalog query' is redundant against readOnlyHint and is the only wasted 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 return shape need not be explained, all 12 params are documented in the schema, and the description supplies the routing context an agent needs to pick this tool over its alternatives. Nothing essential is missing for a filtered, paginated read-only list.

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

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

Schema description coverage is 100% across 12 params, so the schema already documents every filter, including enums-in-text for roles, density and platforms. The description only names four of those dimensions (platform, role, density, canvasPreset), adding no syntax or semantics beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource with scope: 'List public template catalog summaries from Gateway', and enumerates the filterable dimensions. It also draws the boundary against get_template for full slot requirements and against recommend_slideshow_templates for slideshow page selection, so an agent can distinguish it from siblings 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?

Explicit routing: prefer recommend_slideshow_templates for Slideshow page template selection, and use get_template to inspect specific slot requirements. The condition that selects each alternative is named, leaving little to inference.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false), the description discloses non-obvious traits: publication is an immutable promotion, the AST is validated against layout rules, and the call fails when required slots/constraints are violated. That validation-failure and irreversibility context is exactly what annotations cannot convey.

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

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

Front-loaded with purpose and routing before behavioral detail, and every sentence carries information. The final sentence describing the returned Template entity, templateId, slots table, and catalog status partially duplicates the output schema, which is a minor 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?

An output schema exists, so return values needn't be explained, and the description still adds the validation/failure semantics and immutability caveat. For a one-parameter mutation with annotations present, this is complete enough for an agent to call it correctly.

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

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

Schema coverage is 100% for the single draftId parameter, so the schema already documents it fully. The description adds only the implicit notion that the draft is validated, not new syntax or format detail. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Validate and publish an authoring draft into the public or workspace template catalog') and immediately distinguishes itself from siblings by naming update_template_draft and get_template_draft. An agent can tell it apart from other template tools 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?

Gives an explicit trigger ('when draft design and slot contracts are finalized and ready for instantiation'), an explicit exclusion ('If still editing or fixing layout rules, use update_template_draft'), and an inspection alternative ('use get_template_draft'). Nothing is left to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, and the description reinforces this as a 'read-only stateless' query. It goes further by disclosing non-obvious behavior: recent layout families are demoted to avoid visual monotony, and diversity across slides is guaranteed. Minor overlap with annotations in the closing line keeps it from a 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?

Front-loaded with the core action and the sequencing instruction, then alternatives, then behavior. Every sentence carries weight, though the closing 'Behavior: Read-only stateless layout intelligence query' is partly redundant with 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?

Covers purpose, timing relative to create_slideshow_run, alternatives, and behavioral guarantees; with an output schema present, return-value explanation is unnecessary. An agent has everything needed to invoke it correctly in the workflow.

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

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

Schema description coverage is 100% and an output schema exists, so the schema already documents k, seed, platform, canvasPreset, and the page contract fields. The description only paraphrases the contract concepts ('role, density, image requirement') without adding format or constraint detail beyond the schema, matching the baseline 3.

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

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

States a specific verb (recommend) and resource (curated template options per slideshow slide) plus the basis for the recommendation (narrative page contracts: role, density, image requirement). It is clearly distinguishable from siblings like list_templates or get_template, which only expose the raw catalog.

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

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

Gives an explicit trigger ('Call immediately before create_slideshow_run to select templateId per slide') and names the alternative with its own use case ('Use list_templates to browse raw catalog'). When-to-use and when-to-use-something-else are both covered.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, and the description's 'Idempotent state transition' largely repeats that. However, it adds genuine behavioral context beyond annotations: the restored brand becomes 'immediately selectable in brand selectors and default list queries' and the resulting status is 'active'. Auth requirements and error behavior for a non-archived ID remain undisclosed.

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 action and effect, then alternatives, then behavior. Minor redundancy: 'Idempotent state transition' and 'Returns restored Brand with status set to active' restate what annotations and the output schema already convey.

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-required-parameter tool with an output schema, the description covers purpose, effect, and an alternative path adequately. Only error/failure handling (e.g., brand not archived) and permission requirements are absent, which is a modest gap rather than a blocking one.

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

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

Schema description coverage is 100% for the single brandId parameter, so the schema already documents it fully; baseline is 3. The description only implies the ID must reference an archived/trashed brand and adds no format or lookup detail 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 ('Restore') and resource ('Brand'), plus the source state ('previously archived or trashed') and target state ('active status'). An agent can distinguish it from archive_brand, delete_brand, and get_brand 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?

Gives a clear use case ('Call to unhide a brand and make it immediately selectable') and names an alternative ('Use get_brand to inspect tokens before restoring') with its selecting condition. It lacks an explicit when-not (e.g., that archive_brand is the inverse, or what to do if the brand is not archived), so it falls short of a full 5.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds value by naming the two source states it reverses (archived or trashed) and the downstream effect on slide slot editors, though 'Idempotent state transition' largely restates the idempotentHint annotation.

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 core action and effect are front-loaded in the first two sentences. The trailing 'Returns restored Image record visible in default media queries' is somewhat redundant given an output schema exists, costing a bit of efficiency.

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

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

For a single-parameter, idempotent state-transition tool with rich annotations and an output schema, the description covers the action, the states involved, the user-visible effect, and a related tool. Nothing an agent needs 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?

Schema description coverage is 100% and the single imageId parameter is fully documented in the schema. The description adds no syntax, format, or lookup guidance beyond what the schema already says, so the 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 (restore), resource (image asset), and the exact state transition (archived/trashed back to active), which cleanly separates it from archive_image and delete_image in 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?

Gives clear context for when to call it ('unhide a retired asset', 'make it selectable again in slide slot editors') and points to get_image for pre-inspection. It does not state when NOT to use it, e.g. that delete_image is permanent and unrecoverable by this tool, which is the key exclusion an agent would need.

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 and idempotentHint=true, and the description is consistent with them (the 'idempotent state change' line largely echoes the annotation). It does add genuine context beyond the structured fields: the state transition source/target and the fact that the restored record appears in default workspace listings.

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?

Short and front-loaded with the action and state transition first, and the alternative routing after. Minor redundancy: 'restoring it to the default projects view' and 'visible in default workspace listings' restate the same outcome, and the idempotence line duplicates the 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?

For a single-parameter state-change tool with an output schema, the description covers purpose, usage, alternative, and outcome adequately. Missing only edge details such as permission requirements or behavior when the run is already active, which is minor given the annotations and output schema.

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

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

Only one parameter with 100% schema description coverage, so the schema already fully documents runId. The description indirectly clarifies run semantics ('archived or trashed carousel project') but adds no format, constraint, or identifier guidance beyond what the schema provides; 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 (restore) and resource (Slideshow Run), plus the exact source states (archived or trashed) and destination (active workspace / default projects view). This clearly distinguishes it from archive_slideshow_run, delete_slideshow_run, and update_slideshow_run 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?

Gives an explicit usage trigger ('Use to reactivate an archived or trashed carousel project') and names a concrete alternative (get_slideshow_run) with the condition that selects it. It stops short of stating when not to use it, e.g. that calling it on an already-active run is a no-op, so it is clear but not fully closed.

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, non-open-world, so the safety profile is covered; the description nonetheless adds non-obvious operational context: it does not consume quota and that candidates must be confirmed before materializing an asset. It does not discuss rate limits or result ordering, so it falls short of a 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?

Purpose is front-loaded and the sentences are short and purposeful. There is mild redundancy between the description and the schema/annotations (read-only, the ≤8 limit which the limit default already implies), which keeps it from a 5.

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

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

With an output schema present, return values need no explanation; the description covers the remaining agent-relevant gaps — search scope, the get_icon handoff, quota impact and the confirmation step before materializing. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents query, limit, style and collection, including the token-budget guidance on limit. The description only restates the search axes, adding no syntax, defaults or format detail beyond the schema, so the 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 (search) plus resource (Template Icon Catalog / curated Iconify collections) and the three axes of search (keyword, collection, visual style). It also names the follow-up sibling get_icon, so an agent can place it in the workflow without opening another 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?

Explicit when-to-use (designing templates, adding icon decorations), an explicit alternative with its trigger condition (get_icon once an iconId is selected), and a workflow constraint (select ≤8 candidates and confirm before materializing). Nothing about selection is left to inference.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, but the description adds crucial context beyond them: the optimistic concurrency mechanism (requires baseRevision), the specific 409 Conflict response on revision mismatch, and the safe partial-patch behavior preserving unspecified tokens. These details are essential for correct call sequencing and error handling.

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

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

The description is front-loaded with the core action and scope, followed by usage guidance, exclusions, behavioral details, and return value, all in efficient sentences with no wasted words. Every sentence adds distinct value.

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

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

Despite the tool having an output schema (so return values need not be explained), the description still adds critical context about concurrency, error handling, and partial update semantics. Combined with the schema and annotations, an agent has everything needed to call this tool correctly.

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

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

Schema coverage is 100%, so the schema fully documents all eight parameters. The description adds meaningful semantics for baseRevision (concurrency lock, must match latest revision) and the partial-patch behavior, but does not provide additional syntax or format details for the updateable fields beyond what the schema already lists.

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 (Patch) and resource (visual styles, typography, or metadata of an existing Brand), and explicitly names sibling tools create_brand and delete_brand to distinguish the scope. An agent can immediately tell this is a partial update operation, not creation or deletion.

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

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

It provides explicit when-to-use guidance ('Call after get_brand to modify palette or fonts') and clear exclusions ('Do NOT use to create new brands... or to delete'), naming the alternative tools for each excluded case. This fully routes the agent to the correct tool.

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

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

Annotations already cover the mutation/safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), but the description adds context the annotations cannot: the workspace-owner authorization requirement and the partial-update guarantee that only provided fields are modified. It stops short of noting reversibility or idempotency nuances that would earn a 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?

Front-loads purpose, then usage, then exclusions, then constraints and return. Every sentence carries distinct information; nothing is repeated from the title or schema.

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

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

For a 3-parameter mutation with annotations, a 100%-covered schema, and an output schema, the description supplies the missing behavioral pieces (authorization, partial-update semantics, sibling routing). An agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters including the rightsStatus value set. The description restates name/rightsStatus and imageId as the identifier but adds no format or constraint detail beyond the schema; 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 (update), resource (image metadata), the fields in scope (name, rightsStatus), and the lookup key (imageId). It also explicitly distinguishes itself from attest_image and import_image, so an agent can route correctly 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?

Gives positive triggers ('rename images or change categorization tags') and explicit exclusions with the correct alternative for each ('Do NOT use to record legal commercial compliance attestations (use attest_image instead) or to replace image binary pixels (use import_image)'). Also states the authorization prerequisite (workspace owner).

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

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

Annotations already establish readOnly=false, destructive=false, idempotent=false, and openWorld=false, but the description adds substantial context beyond them. It explains that unspecified fields are preserved, that baseRevision is required for optimistic concurrency, that a mismatch returns 409 Conflict with no auto-merge and requires a fresh get_slideshow_run, and that the response increments the revision number.

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

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

The description is front-loaded with the core action and then proceeds through prerequisites, exclusions, concurrency behavior, and patch modes. Despite covering a complex mutation, every sentence contributes operationally relevant context and there is little or 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 complex partial-update tool with eleven parameters, nested objects, an output schema, and non-idempotent concurrency semantics, the description covers the necessary operational context. It explains mutation scope, preservation semantics, revision locking, conflict behavior, and return behavior, so the agent has what it needs to call the tool correctly.

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

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

Schema coverage is 100%, so the schema already documents all eleven parameters. The description still adds useful semantic relationships beyond the schema, particularly that pageIndex is 0-indexed and must be paired with slots, layout, style, or decorations for single-slide patches, and that pack overrides the entire deck for whole-deck updates.

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

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

The description opens with a specific verb and resource: partially update an existing Slideshow Run by runId. It enumerates the mutable aspects (slide copy, slot bindings, layout, styling, brand settings) and explicitly distinguishes this tool from create_slideshow_run and delete_slideshow_run, so an agent can identify it without opening 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?

It gives explicit when-to-use guidance: call get_slideshow_run first to obtain the revision and slide data, and do not use this tool to create or delete runs. It also states when to provide pageIndex with slots/layout/style versus when to provide pack for the entire deck, leaving no routing ambiguity.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), so the read/write and idempotency question is settled structurally. The description nonetheless adds real value beyond them: draft-owner authorization requirement, safe partial-patch semantics (unmentioned properties untouched), automatic layout-rule validation on save with returned warnings, and the shape of the returned record. This is useful added context, though it stops short of describing failure modes or rate/concurrency behavior for an iterative 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?

Six tight sentences ordered purpose → usage → exclusions → prerequisites → mutation semantics → side effects → return. It is dense but front-loaded, and each sentence carries information an agent needs before calling; nothing is padding.

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, yet the description still summarizes the returned TemplateDraft with validation status and AST snapshot. Combined with auth, partial-patch, and validation-trigger disclosures, it is complete enough for a 5-param mutation with nested objects; only granular failure/error behavior is unaddressed.

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

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

Schema description coverage is 100% with all five properties documented, including the nested authoringSource, selectionMetadata, and theme objects, so the baseline is 3. The description's phrase 'layer AST, slot definitions, selection metadata, or theme tokens' loosely maps onto those parameters but adds no format, constraint, or merge-syntax detail beyond the schema's own per-field descriptions.

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

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

Opens with a specific verb+resource pair ('Update ... existing template authoring draft by draftId') and enumerates the mutable facets (layer AST, slot definitions, selection metadata, theme tokens). It explicitly distinguishes itself from create_template_draft, get_template_draft, and publish_template_draft, so an agent can select it 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?

Gives positive guidance ('Call iteratively to refine draft layout and slot contracts during authoring') plus three explicit when-not cases, each naming the correct sibling for the excluded job. Nothing is left to inference.

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