clipkit

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

Annotations already flag readOnlyHint=false and destructiveHint=false. The description adds meaningful behavioral context: the element is validated as part of the whole project before being added, unrecognized keys are flagged, and default placement vs nested behavior is disclosed. This goes 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 action and scope. Every sentence provides either usage guidance or parameter context, with no filler or redundancy. It is appropriately sized for the tool's complexity.

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

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

Given the rich input schema, three parameters, and existing output schema, the description covers purpose, usage boundaries, and validation behavior. It even directs the user to get_schema for type-specific details, filling potential gaps. This is complete for the tool's complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by enumerating valid element types and pointing to get_schema for per-type fields, enriching the element parameter's semantics. It also clarifies parent_id behavior, complementing the schema 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 tool appends a single element to an existing project using the verb 'Append' plus the resource. It distinguishes from set_project by explicitly advising use of set_project for bulk or composition, making the purpose unambiguous.

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

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

The description provides explicit usage guidance: it says to use set_project instead when creating a composition or bulk-adding elements. It also instructs calling get_schema(element_type) for exact fields, and explains the parent_id option for nesting versus top-level default placement.

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

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

Annotations declare destructiveHint=false, but the description states that passing an existing project_id resets that project to blank, which is a destructive action. This is a direct contradiction, requiring a score of 1 per the rubric.

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 dense sentences cover purpose, defaults, usage order, and reset behavior without wasted words. Each sentence earns its place and the description is appropriately front-loaded with the core action.

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

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

Description provides defaults, when to call, reset behavior, and note to record the returned id. Since an output schema exists, return values need not be explained. However, the contradiction with the destructiveHint annotation leaves safety ambiguity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful semantics for project_id by explaining reset vs. fresh creation, and it restates defaults for width/height/duration/frame_rate/output_format, which reinforces but goes slightly beyond the schema.

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

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

Clearly states it creates a new, blank Clipkit project with specified dimensions and duration, and returns project_id. The description also distinguishes fresh creation from resetting an existing project, which separates it from siblings like create_promo or 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?

Explicitly instructs 'Call this first when starting a new video' and explains when to pass or omit project_id, giving actionable usage guidance. It doesn't compare directly with alternatives, but context makes the usage 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?

The description discloses key behaviors: it bakes in camera, glass, lighting, motion blur, timing, and layout, and returns an editor link. While annotations cover destructive/read-only hints, the description adds context about the output and scene variety. It doesn't mention project creation/overwrite explicitly, but that is covered by schema and the overall framing.

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

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

The description is long but every sentence earns its place: it gives a one-sentence overview, usage guidance, scene-type cheat sheet, and a theming tip. It is front-loaded with the main purpose and avoids redundancy.

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

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

Given the tool's complexity (nine scene types) and rich schema, the description is remarkably complete. It covers what the tool does, when to use it, alternatives, scene types with their parameters, and a best-practice theming tip. It also mentions the output (editor link).

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, but the description adds value by explaining each scene type's purpose and required fields (e.g., 'hero (glass-orb logo reveal: wordmark, tagline?)') and recommending 'theme mux' for data scenes. This enriches the schema's raw field definitions.

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 what the tool does: 'Assemble a designed-looking promo/intro/product/data video from the Clipkit pattern library' with a specific verb and resource. It also distinguishes itself from siblings by positioning this as 'one fast option' and explicitly contrasting with set_project for full creative control.

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

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

It explicitly says when to use it ('FAST option when a conventional promo structure fits') and when not to ('NOT a default; for anything specific or original, author the JSON yourself and call set_project'). It also gives practical guidance to 'MIX scene types to fit the brief and vary the structure'.

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 convey destructiveHint=true and readOnlyHint=false. The description adds useful behavioral context beyond this: it can delete elements nested inside groups or masks, and it enforces a minimum top-level element constraint. This provides additional operational detail without contradicting 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 compact: two sentences, with the primary action and scope stated up front. The additional constraint about top-level elements is valuable and succinctly expressed. Every sentence earns its place 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?

For a deletion tool with two parameters and an output schema, the description covers the key operational aspects: scope (anywhere in tree), context (existing composition), and a critical constraint (must keep at least one top-level element). The schema handles parameter details, and annotations handle safety, so the description 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 description does not add parameter-specific semantics; it merely references 'the given id'. The schema already thoroughly documents both id and project_id, so the description adds no extra value here.

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: 'Delete the element with the given id, anywhere in the tree.' It also specifies the scope (including nested elements) and positions it as a tweak to an existing composition, distinguishing it from creation tools like add_element. The constraint about keeping at least one top-level element adds further clarity.

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

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

The description implies usage context: it is for modifying an existing composition by deleting an element. It does not explicitly name alternatives or state when not to use it, but the context is clear given sibling tools like add_element and edit_element. This aligns with 'clear context, no exclusions'.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is clear. The description adds behavioral context by listing the exact content of the summary (dimensions, fps, duration, element breakdown, per-track timeline, render-time warnings) and notes the performance trade-off ('Much cheaper to read'). This goes beyond what annotations provide.

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

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

Two sentences, each carrying substantial information. The first sentence opens with the action and lists the summary contents; the second provides the usage rationale and alternative. No wasted words 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?

There is no output schema, but the description compensates by enumerating all the major fields the summary contains. It also positions the tool relative to get_project and explains when to use it. For a read-only tool with one optional parameter, this is fully sufficient for an agent to select and invoke it.

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

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

Schema description coverage is 100% and the sole parameter (project_id) has a thorough, self-contained explanation including when to omit it. The tool description itself does not add any parameter-level semantics, so per the rubric 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 starts with a specific verb ('Return') and clearly defines the resource ('a compact, human-readable summary of the current project'), then enumerates the contents. It also distinguishes the tool from the sibling get_project by contrasting 'compact' vs. 'full JSON', making it easy to know which tool to pick.

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 the intended use cases: 'use it to orient yourself or sanity-check structure without dumping the whole source.' It also names an alternative (get_project) and explains why this tool is preferable when you need only a summary, which is exactly the kind of guidance an agent needs.

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

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

The description thoroughly discloses merge semantics: only included keys change, nested values replace whole keys, null removes keys, the id can target elements anywhere in the tree (including nested in groups or masks), and the result is re-validated. This goes well beyond the annotations (which only say readOnlyHint=false, destructiveHint=false) and gives the agent essential behavioral expectations.

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

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

The description is concise yet information-dense: four sentences cover the core mechanism, scope, nested-value behavior, null handling, alternative tools, and validation. Every sentence adds critical context with no redundancy or filler.

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

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

Given the tool's complexity (merge patch, nested objects, arbitrary tree locations) and the existence of an output schema, the description is complete. It covers what the tool does, how patching works, edge cases (null removal, nested replacement), and safety (re-validation). No gaps remain for the agent to misinterpret.

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

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

The schema already covers all parameters with descriptions (100% coverage), so the baseline is 3. The description adds value by explaining the 'patch' semantics with an example (keyframe_animations) and clarifying that id can reference nested elements anywhere in the tree, which is not in the schema. This nuanced guidance justifies a score above baseline.

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

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

The description opens with a specific action: 'Change fields on the element with the given id by merging in a partial element'. It clearly identifies the resource (element) and mechanism (merge). It also distinguishes from siblings by explicitly framing it as 'TWEAKING an existing composition' and contrasting with 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?

Provides explicit usage guidance: 'This is for TWEAKING an existing composition. To create a composition or change many elements at once, edit the JSON and call set_project instead.' This tells the agent when to use this tool and what to use instead, effectively differentiating it from add_element and set_project.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds context that the result is the 'full' current source, implying no filtering or partial views, and emphasizes the 'current' stateful nature of the project. It does not detail error behavior when no project exists, but the added context is valuable.

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

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

The description is two short sentences, front-loading the core function and then listing useful use cases. Every word earns its place, and there is no redundant or vague phrasing.

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 no output schema, but the description, combined with strong annotations and a well-documented parameter, gives enough context for an agent to understand what it returns and when to use it. It could mention behavior when no project exists (e.g., error or empty result), but this is a minor gap given the low 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% and the single parameter's description in the schema is detailed, covering when to pass it and when to omit. The tool description itself does not add any additional parameter semantics, so the baseline of 3 applies.

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

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

The description states a specific action ('Return the full current Clipkit source as JSON') with a clear resource ('the full current Clipkit source'). It also distinguishes itself from siblings like 'describe_project' by emphasizing raw JSON output for inspection, rendering, and composing edits.

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 use cases: inspect the project, pass to a render pipeline, or compose follow-up edits. It does not explicitly state when not to use it (e.g., preferring describe_project for a summary), but the use cases are clear enough to guide selection.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context: the tool can return either the full schema or a filtered subset depending on the element_type parameter, with size implications ('much smaller'), and emphasizes the schema is 'authoritative' and 'generated from the protocol.' No contradictions with annotations.

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

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

The description is three sentences, each earning its place: statement of purpose, explanation of the two modes, and actionable usage guidance. No redundant or filler content.

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

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

For a tool with one optional parameter and no output schema, the description is complete: it explains the input options, the return value's nature (exact field names, types, enums), and connects to sibling authoring tools. The absence of an output schema is compensated by the explicit statement that it returns a JSON Schema, making the return self-evident.

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

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

The input schema fully describes the element_type parameter (coverage 100%), so the baseline is 3. The description adds concrete examples ('text', 'shape', 'particles') and clarifies the no-argument behavior, reinforcing the schema semantics and providing helpful usage context. This elevates it above baseline.

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

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

The description clearly states the tool's function: 'Return the authoritative JSON Schema for a Clipkit Source — exact field names, types, and enums, generated from the protocol.' It uses a specific verb ('Return') and resource ('JSON Schema for a Clipkit Source'), and further distinguishes itself from sibling tools by referencing authoring workflows (set_project / add_element). This is a clear, specific purpose that is not confused with other tools like get_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 gives explicit when-to-use guidance: 'Use this when authoring with set_project / add_element so you never guess a field.' It also explains the two calling modes (with or without element_type). However, it does not name alternatives to avoid or explicitly state when not to use it, so it falls short of a perfect score.

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

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

The description goes beyond the annotations by disclosing the fetch-and-host behavior, the returned asset_url, and the exact limits (5 assets, 100 MB total, 50 MB per file) plus the recommended fallback action (tell user to open project and sign in). This adds substantial context beyond the schema and 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 efficient sentences, each carrying distinct information: what it does, why to use it, limit handling, and the project_id requirement. It is front-loaded with the main purpose and avoids fluff, achieving high information density.

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 (fetch and host, limits, return value) and the presence of an output schema, the description covers all essential decision-making aspects: purpose, rationale, constraints, and user guidance. It is complete for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, and the schema already provides detailed context for each parameter, especially project_id. The description adds only a brief 'Requires project_id' and mentions the asset_url return, but these are already implied or better explained in the schema. No significant extra semantic value.

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 fetches a remote media URL (image/video/audio) and hosts it on Clipkit, returning a stable asset_url. This specific verb-resource pairing distinguishes it from sibling tools like add_element, which adds elements rather than hosting assets.

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

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

It explicitly says when to use this tool ('so the project's media survives') and provides reasoning (original link may rot, be private, or block hotlinking). It also gives operational guidance for limit handling, though it doesn't explicitly name alternatives or when not to use it.

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

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

Annotations already disclose destructive and open-world hints; the description adds useful context by explaining the project_id behavior ('load into that project' vs 'load into a new one') and that it returns a project_id. It does not explicitly warn about overwriting existing content, but the annotations cover the safety profile and nothing contradicts them.

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

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

Three terse sentences that front-load the core action, then provide usage context, then parameter behavior. Every sentence earns its place with 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 the output schema exists and annotations are present, the description covers all essential aspects: purpose, mechanism, return value, relationship to siblings, and parameter behavior. It is complete for a tool of this complexity.

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

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

Schema coverage is 100%, but the description adds meaningful semantics: it clarifies the id_or_url accepts a share id or editor URL with an example, and it explains the behavior of omitting vs providing project_id beyond the schema description. This goes beyond the schema fields.

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

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

The description uses a specific verb ('Import') and resource ('previously shared project') and clearly states the outcome ('as the current project'). It explicitly distinguishes from siblings by calling itself 'the round-trip for open_in_editor', making its role unambiguous.

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

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

The description provides clear when-to-use guidance ('Use this to continue working on a project the user opened in the editor or shared earlier') and defines the relationship with open_in_editor. It does not explicitly list exclusions or alternative tools, but the round-trip framing is effective 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=false, openWorldHint=true, destructiveHint=false, so the safety profile is known. The description adds value by disclosing that it validates the project, returns a URL, and intentionally does not render anything. However, it does not go into side effects of creating a shareable link (e.g., making the project accessible), but with annotations covering destructive/read-only, this is adequate.

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

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

The description is three concise sentences, front-loaded with the main purpose, then differentiation, usage timing, and return value. Every sentence contributes new information, and it is well-structured for quick parsing.

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 only one parameter, a detailed schema, an output schema, and annotations, the description covers what it does, when to use it, and what it returns. No critical gaps remain for an agent to invoke it correctly.

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

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

Schema coverage is 100% and the schema's project_id description is thorough, explaining when to pass it and when to omit it. The tool description adds no parameter-specific instructions beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool creates a shareable link that opens the project in the Clipkit web editor. It specifies the action (create a link), the resource (current project), and differentiates from render_video by noting nothing is rendered. This distinguishes it from sibling tools like preview_still or validate_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 says 'Use after composing or editing,' giving a clear temporal context. It also contrasts with render_video by stating 'nothing is rendered — that's render_video,' providing an explicit alternative. This gives clear when-to-use guidance and a notable exclusion.

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

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

Annotations already mark the tool as read-only and non-destructive. The description adds useful behavioral context beyond annotations: it notes that stills are free (no credit cost), that the output is a viewable PNG image, and that the time parameter defaults to 0. This provides cost and output-format transparency without contradicting the annotations.

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

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

The description is front-loaded with the core purpose and then elaborates on usage and cost. It consists of five sentences, all of which contribute value (purpose, why, when, cost, default). It is slightly longer than the minimal effective description but remains focused and free of 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 the annotations, full schema descriptions, and the presence of an output schema, the description is complete. It clearly communicates the tool's purpose, when to use it, cost implications, and default behavior. The `project_id` parameter is adequately covered by the schema, and return value details are implied by the output schema, so no additional explanatory burden falls on the description.

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

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

Schema description coverage is 100%, so the baseline is 3. The description only redundantly mentions the `time` parameter ('Pass `time` (seconds) to choose the frame; defaults to 0') which is already fully described in the schema. No additional meaning is added for `project_id` or `time` 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?

The description clearly states the tool's function: 'Render a single frame of the current project to a PNG and return it as an image you can look at.' This uses a specific verb ('render') and resource ('single frame of the current project'), and distinguishes it from sibling tools by emphasizing that it produces a visual image for inspection.

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: 'This is how you check your work — in chat there is no other way to see what a composition actually looks like. Use it liberally: after composing, after edits, and at different times to inspect motion.' It also contrasts with render_video by noting 'Stills are FREE (credits are only spent by render_video),' clearly indicating when to use this tool versus the alternative.

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

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

Annotations already assert read-only and non-destructive, so the description adds value by disclosing doc sizes (~8KB, ~4-5KB), content summaries, and the note that these docs are also MCP resources exposed as a tool because resources aren't always model-readable. This explains the tool's presence and behavior without contradicting annotations.

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

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

The description front-loads the core behavior, then organizes the seven topics compactly with quoted terms and semicolons. All details are relevant to tool selection, 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?

For a simple one-parameter tool, the description covers all topics, sizes, use cases, and even the tool-vs-resource rationale. There's no output schema, but 'as text' plus topic descriptions give sufficient information to invoke correctly.

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

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

The schema only says 'Which doc. Default agents.' The description elaborates on each enum value with purpose, size, and usage context, greatly exceeding 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 opens with a clear action ('Return a canonical Clipkit doc as text'), names the resource (Clipkit docs), and enumerates distinct topic values, making it easy to distinguish from sibling tools that manage projects or elements.

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 selection guidance: the 'card' is recommended for authoring, pattern cards should be loaded alongside the card for matching archetypes, and 'agents' should only be fetched if the card doesn't cover a need. This tells the agent exactly when to use each topic and why the tool exists.

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 several behavioral traits beyond the annotations: it warns that omitting project_id 'creates a NEW, unrelated project and strands the old one,' notes that input is validated against @clipkit/protocol, and explains that 'the runtime ignores unrecognized keys, and this tool flags any it does not recognize.' These details align with the destructiveHint annotation and add valuable operational 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 appropriately sized for the tool's complexity. It is front-loaded with the core purpose, followed by usage rules, revision guidance, and validation/shape details. Every sentence earns its place—there is no filler or redundancy, and the logical flow makes it easy to parse.

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

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

Given the tool's high complexity (nested source object, side effects, validation), the description covers all necessary context: return value (project_id), when to use alternatives, revision behavior, validation details, and pointer to get_schema for exact field definitions. The presence of an output schema does not reduce the need for this explanation, as the description adds decision-making context beyond any structured fields.

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

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

Although the schema covers 100% of parameters with descriptions, the tool description adds significant meaning: it elaborates on project_id's usage ('ALWAYS pass it once a project exists in this conversation'), explains the consequences of omission, and describes the source object's shape, noting optional fields and directing to get_schema for exact field names. This goes well beyond the schema's terse descriptions.

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

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

The description clearly states the tool's function: 'Replace the entire project with the given source JSON, returning its project_id.' It uses a specific verb ('replace') and resource ('project'), and explicitly differentiates from siblings by naming edit_element, add_element, and delete_element as alternatives for single-element changes.

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

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

The description provides explicit when-to-use guidance: 'This is the PRIMARY way to build: use it to create a composition or to add/change many elements at once.' It also gives a clear exclusion rule: 'To tweak a single element in an existing project, use edit_element / add_element / delete_element instead.' The 'REVISION RULE' paragraph further details when to pass project_id versus when to omit it, offering unambiguous decision guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds valuable behavioral detail by enumerating specific render-time warning categories (non-ASCII text, clipping past composition end, missing duration) that the runtime would silently drop or clip. 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?

Two dense sentences carry all essential information: what the tool does, what specific warnings it catches, when to run it, and how it differs from a sibling. No filler or repetition of schema/annotation contents.

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

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

The description covers purpose, usage timing, alternatives, and provides concrete examples of edge-case warnings. Since an output schema exists, not detailing return values is fine. This is fully complete for a validation tool in this context.

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

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

The sole parameter project_id is fully documented in the input schema with a detailed description about when to pass or omit it (schema_description_coverage=100%). The tool description adds no additional parameter semantics, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool runs the @clipkit/protocol validator against the current project and also surfaces render-time warnings beyond schema validity. It distinguishes itself from describe_project by explicitly pointing to that sibling 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?

Provides explicit when-to-use guidance: 'Run it before you share or render the project.' It also names an alternative (describe_project) for when a fuller read-back is needed, making the tool's place among siblings clear.

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