clipkit

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

Description reveals validation before addition, unrecognized keys flagged, and default behavior (top level vs nested via parent_id). This adds context beyond the minimal annotations (readOnlyHint=false, destructiveHint=false). Minor gap: no mention of side effects like overwriting.

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 focused sentences, front-loaded with core purpose, each sentence adds distinct information. No redundancy or fluff.

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

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

Given 3 parameters, nested objects, and presence of output schema, the description covers purpose, usage, parameter context, and behavioral notes fully. Output schema handles return values.

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

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

Schema covers 100% with descriptions; description adds value by explaining parent_id optionality (omit for top level, pass for group nesting) and project_id usage (omit when single local project).

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

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

Explicitly states 'Append a single element to an existing project' with examples (TWEAK, dropping in caption or shape) and distinguishes from set_project for bulk operations.

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

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

Provides clear when-to-use and when-not-to-use: 'To create a composition or add several elements at once, build the JSON and use set_project instead.' Also directs to get_schema for field details.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description adds value by explaining that passing an existing project_id resets it to blank (a write operation), and that defaults are applied. It does not contradict annotations, and provides additional behavioral context beyond the structured fields.

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

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

The description is four sentences, front-loaded with the core purpose and defaults, then usage guidance and reset behavior. Every sentence adds essential information without redundancy or unnecessary detail.

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

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

Given the tool's complexity (8 parameters, no required, output schema exists), the description is largely complete. It explains the main usage and reset capability. However, it does not mention parameters like background_color or output_dither, though these are covered in the schema. The presence of an output schema reduces the need to describe return values.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds marginal value by naming defaults for width, height, duration, frame_rate, and output_format, and by explaining the dual use of project_id. However, all parameters are already well-described in the schema, so the description does not significantly enhance parameter understanding.

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

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

The description clearly states the tool creates a new blank Clipkit project, returns a project_id, and lists default dimensions and duration. It distinguishes itself from siblings like create_promo by specifying it's for a blank project, and mentions reuse for resetting, which is a unique behavior.

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

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

The description explicitly says 'Call this first when starting a new video,' providing clear usage context. It also explains how to pass an existing project_id to reset it, but does not explicitly state when not to use the tool or compare with alternatives like load_project or set_project, though the context is sufficient.

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

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

Annotations include destructiveHint: true, and the description adds context that the tool 'bakes in' camera, lighting, etc., modifies the project, and returns an editor link. No contradiction with annotations; description adds value by explaining the automated process.

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

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

Description is front-loaded with the main purpose, then provides usage constraints, then lists scene types. It is informative but could be slightly more concise; however, every sentence adds value and it avoids redundancy with 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 the complexity (6 params, nested scenes) and presence of output schema, the description covers purpose, usage, scene structure, and output (editor link). It lacks detailed info on output schema (but that is separate), so not a 5.

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

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

Schema coverage is 100%, baseline 3. Description adds extra meaning by detailing scene types, their required fields, and providing examples (e.g., 'a single kinetic headline, three title cards...'). Also notes that data scenes look best with theme 'mux', which is not in schema.

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

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

The title and description clearly state the tool composes a promo from prebuilt scenes (a specific verb+resource). It distinguishes itself from sibling set_project by labeling itself as a 'fast option' and explicitly contrasting with the 'full creative range' of set_project.

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

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

The description explicitly states when to use this tool ('when a conventional promo structure fits') and when not ('for anything specific or original, author the JSON yourself and call set_project'). It also provides guidance on mixing scene types and suggests 'mux' theme for data scenes.

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

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

Description aligns with annotations (destructiveHint=true) and adds context: deletion works even for nested elements, and it's a 'tweak' affecting the composition. It also warns about the minimum element requirement, which is not in annotations.

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

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

Two sentences, no wasted words. Front-loaded with the primary action and follows with clarifications. Every sentence adds value.

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

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

For a delete operation with an output schema, the description covers the core behavior (scope, constraint) sufficiently. Agent can infer what to expect.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add additional meaning beyond what the schema provides for the parameters (id, project_id). It mentions 'by id' but no extra context.

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

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

The description clearly states the verb ('Delete'), the resource ('element'), and the identifier ('by id'). It specifies scope ('anywhere in the tree... including nested') and distinguishes from siblings like add_element or edit_element.

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

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

The description provides a key usage constraint ('project must keep at least one top-level element'). It implies when to use (to remove an element) but does not explicitly state when not to use or suggest alternatives.

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

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

Annotations already declare readOnlyHint=true. Description adds valuable context about return contents (dimensions, fps, duration, element breakdown, timeline, warnings) and cost comparison. No contradictions.

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

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

The description is one sentence listing contents, followed by a usage comparison. It is concise but could be slightly more structured (e.g., bullet points). No wasted words.

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

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

For a simple read-only tool with one parameter and no output schema, the description fully explains what the tool returns and when to use it. It addresses the lack of output schema by enumerating return contents.

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

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

Schema description coverage is 100% for the single parameter. Description does not add new meaning beyond the schema's provided description, which already mentions omitting for local projects. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'Return' and resource 'compact, human-readable summary of the current project', listing specific contents (dimensions, fps, etc.). It distinguishes from sibling 'get_project' by emphasizing cheaper and more readable format.

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

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

Explicitly tells when to use: 'use it to orient yourself or sanity-check structure'. Provides contrast with 'get_project' by noting it's cheaper and avoids dumping full JSON.

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

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

The description adds significant behavioral details beyond the sparse annotations: it explains the merge semantics, that null removes a key, that nested values replace the entire key, and that the result is re-validated. No contradiction with annotations.

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

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

The description is four sentences, each serving a purpose: explaining the core merge behavior, clarifying id scope, providing usage alternatives, and mentioning re-validation. It is well-structured but could be slightly more concise.

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

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

Given the tool's complexity (3 parameters, nested objects) and the presence of an output schema (not shown but referenced), the description covers all necessary aspects: what it does, how to use it, scope, alternatives, and behavior. It is complete for an AI agent to understand correct usage.

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

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

The input schema already describes all three parameters (100% coverage). The description adds value by clarifying that nested objects can be passed to replace a key and that setting a key to null removes it, which is not explicitly in the schema descriptions.

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

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

The description clearly states the tool changes fields on an existing element via partial merge. It distinguishes from siblings by explicitly mentioning that to create or change many elements, one should use set_project instead.

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

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

The description provides explicit guidance on when to use (tweaking an existing composition) and when to use alternatives (set_project for creation or bulk changes). It could mention specific cases where delete_element might be more appropriate, but overall it gives clear context.

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

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

Annotations already provide readOnlyHint=true, indicating no destructive side effects. The description adds that the tool returns the 'full current' source as JSON, clarifying the scope and format of the output. No contradictions; the description complements the annotations.

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

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

The description is two sentences: first states the core purpose, second lists practical use cases. Every word is necessary, no redundancy, and the most critical information (return format) 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?

The tool is simple with one optional parameter and no output schema. The description covers the key aspects: what it returns (full JSON) and common use cases. It does not detail the contents of the JSON, but given the tool's simplicity and domain assumptions, it is adequately complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The tool description does not add extra details about the 'project_id' parameter beyond the schema's description, which already explains when to use it. Thus, no additional value is provided.

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

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

The description clearly states the tool returns 'the full current Clipkit source as JSON', specifying both the verb (return) and the resource (full project JSON). It distinguishes from siblings like 'describe_project' by providing the raw data format. Additional use cases (inspect, render pipeline, compose edits) further clarify purpose.

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

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

The description explicitly says 'Use this to inspect the project, pass it to a render pipeline, or compose follow-up edits', giving clear guidance on when to use. It does not explicitly mention when not to use or name alternatives, but the context of siblings like 'describe_project' and 'get_schema' implies differentiation.

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, so safety is clear. The description adds behavioral context: 'generated from the protocol', 'authoritative', and size implications (full vs. subset). It does not contradict annotations.

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

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

Two efficient sentences: first establishes purpose and nature, second provides usage modes and rationale. No wasted words; front-loaded with key information.

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

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

Given the simplicity (one optional param, read-only, no output schema), the description fully covers purpose, use cases, and two operational modes. It is complete for an agent to use correctly.

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

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

Schema coverage is 100% with a single parameter having enum and description. The description adds value by explaining the effect of omitting (full schema) vs. providing element_type, including examples and size comparison.

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

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

The description clearly states the tool returns the authoritative JSON Schema for a Clipkit Source, with verb 'return' and specific resource. It distinguishes from siblings by focusing on schema retrieval rather than project manipulation.

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

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

The description explicitly says when to use: 'when authoring with set_project / add_element so you never guess a field'. It also explains the two modes (with or without element_type). It could be more explicit about when not to use (e.g., for actual project data), but the context is clear.

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

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

Annotations (readOnlyHint=false) already indicate mutation; description adds that the tool hosts media on Clipkit. It also discloses anonymous project limits. However, it contradicts the input schema by saying 'Requires project_id' while schema marks it as optional, causing confusion. The description doesn't clarify idempotency or whether re-ingesting the same URL returns the same asset.

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

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

The description is three sentences with the core action front-loaded. It efficiently adds limit details and fallback instruction. One sentence is long and could be split, but overall every sentence contributes value without redundancy.

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

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

Given the tool has an output schema (unshown) and 100% schema parameter coverage, the description adequately covers purpose, limits, and fallback behavior. It omits error handling beyond limits, but the output schema can fill in return values. Slight gap in explaining the impact of omitting project_id.

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

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

Schema description coverage is 100%, so baseline is 3. However, the description for 'url' repeats the schema verbatim, adding no value. For 'project_id', the description says 'Requires project_id' which directly contradicts the schema's note that it can be omitted for local projects. This misleads the agent. 'filename' is mentioned as 'Optional display name,' which aligns with schema but adds no new insight.

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

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

The description clearly states the tool's action: 'Fetch a remote media URL and HOST it on Clipkit, returning a stable asset_url.' It specifies the resource (remote media) and distinguishes itself from siblings like 'preview_still' or 'add_element' by focusing on hosting media for permanence.

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

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

The description explains why to use this tool (media survival, prevent hotlinking) and provides context for limits (anonymous projects: 5 assets/100 MB/50 MB per file). It advises using 'open_in_editor' when limits hit. However, it does not explicitly state when not to use it or list alternative approaches for media that doesn't need hosting.

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

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

Annotations indicate destructiveHint=true but the description does not reveal what gets destroyed or overwritten. It mentions loading into a project but does not clarify side effects like overwriting the current session. No contradiction with annotations.

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

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

Three concise sentences, front-loaded with purpose, then usage, then parameter guidance. No unnecessary words.

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

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

Given an output schema exists, the description adequately covers purpose, usage, and parameter semantics. Missing mention of destructive behavior is a minor gap but partially covered by annotations.

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

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

Adds value beyond the 100% schema coverage by explaining that omitting project_id creates a new project, clarifying a key usage pattern not in the schema's property descriptions.

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

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

The description clearly states the tool imports a shared project by share ID or editor URL and returns a project_id. It distinguishes from siblings like 'open_in_editor' and 'create_project' by positioning itself as the round-trip operation.

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

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

Provides explicit context for when to use (after sharing) and how to choose between loading into an existing project vs. a new one. However, it lacks explicit instructions on when not to use or direct comparisons to all alternatives.

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

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

Annotations already indicate not read-only and not destructive. Description adds that it validates the project and returns a URL, which details the behavior beyond annotations. However, it doesn't mention any error conditions or side effects.

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

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

Two sentences with no wasted words. Front-loaded with the main action, then provides scope and sibling differentiation.

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

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

Given the simple tool with one optional parameter, the description is complete. It mentions output (returns a URL) and uses context from annotations and schema. No gaps.

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

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

Schema description already covers the parameter. The description adds value by explaining where to obtain the project_id and when to omit it, which helps correct invocation.

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

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

The description clearly states it validates and creates a link to open the project in the web editor, and explicitly distinguishes from render_video by noting nothing is rendered. The verb 'create' and resource 'link' are specific.

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

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

Explicitly says 'Use after composing or editing.' Also clarifies what it does not do ('nothing is rendered — that's render_video'), providing clear alternative and usage context.

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

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

Annotations already declare readOnlyHint and openWorldHint. Description adds that stills are free (no credits), aligning with readOnly. No contradictions.

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

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

Concise single paragraph, front-loaded with action, then guidance, cost, and parameter hint. Every sentence adds value.

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

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

Comprehensive for a simple tool: covers purpose, usage, cost, parameter. Output schema exists so return format need not be specified.

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

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

Schema coverage is 100% with good descriptions. The description adds nothing beyond 'pass time (seconds) to choose frame; defaults to 0' which mirrors schema.

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

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

The description clearly states the tool renders a single frame to PNG and returns it as an image. It distinguishes from sibling render_video by noting cost difference.

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

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

Explicitly tells when to use: check work after composing/edits, and inspect motion. Notes it's the only way to see output in chat and encourages liberal use.

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

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

Annotations already mark readOnlyHint=true; description adds context about doc sizes and resource-to-tool mapping. No behavioral gaps or contradictions.

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

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

One paragraph with no wasted words; main action front-loaded, all relevant information included efficiently.

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 simple structure (1 optional param, no output schema), the description fully covers what the tool returns and when to use each topic.

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

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

While schema covers 100% of params and enum values, the description explains each value's content, size, and intended use, far surpassing the schema's minimal description.

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

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

The description clearly states the verb 'Return' and the resource 'canonical Clipkit doc as text'. It distinguishes each topic with specific sizes and use cases, making it 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?

Explicit guidance on which topic to choose: card is recommended, patterns loaded alongside, agents as fallback. Also explains why the tool exists (resources not always model-readable).

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

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

The description discloses that it replaces the entire project (aligning with destructiveHint=true), validates input against a protocol, and returns an error for invalid inputs. It also notes that unrecognized keys are flagged by this tool but ignored at runtime. Annotations already provide destructive hint, but the description adds useful context.

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

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

The description is well-structured: it starts with the primary use case, then provides guidance on alternatives, then explains parameter semantics and validation. Each sentence adds value, though it is somewhat lengthy. It is front-loaded with key information.

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

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

Given the tool's complexity (nested objects, two parameters, output schema present), the description covers purpose, usage context, parameter semantics, validation behavior, and error handling. It also references get_schema for further detail, ensuring completeness.

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

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

Schema coverage is 100%, but the description adds meaning: it outlines the shape of the source parameter (width, height, duration, etc.) and explains that element fields include type, base fields, and type-specific fields. It also clarifies that omitting project_id creates a new project. This enriches the schema.

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

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

The title 'Replace the entire Clipkit project' and description clearly state the tool's purpose as the primary way to build a composition or add/change many elements at once. It distinguishes from sibling tools like edit_element, add_element, and delete_element by specifying when each should be used.

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

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

The description explicitly states when to use this tool ('PRIMARY way to build') and when not to ('To tweak a single element… use edit_element / add_element / delete_element instead'). It also explains that passing an existing project_id replaces it, while omitting it creates a new one.

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

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

Annotations already indicate readOnlyHint=true, so the description adds value by detailing specific runtime warnings (emoji, missing duration, etc.) beyond schema validation. No contradictions.

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

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

Description is several sentences but each adds value; front-loaded with main purpose. Slightly verbose but not wasteful.

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

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

With one optional parameter and output schema present, the description provides sufficient context including what validation covers and typical use case, meeting completeness for this complexity.

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

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

Schema description coverage is 100%, so the parameter (project_id) is well-documented in the schema. The description adds minimal extra meaning, warranting baseline score.

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

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

The description clearly states the tool validates the project and surfaces render-time warnings, distinguishing it from siblings by referencing describe_project for a fuller timeline read-back.

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

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

Explicitly advises to run before sharing or rendering, and directs to describe_project for alternative use, providing clear when-to and when-not-to guidance.

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