Server Quality Checklist

Tool Scores

• create_projectA
  3.8/5.0
  Behavior1/5

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

  The description states that passing an existing project_id 'reset[s] that project to blank,' which is a destructive action, while annotations declare destructiveHint=false. This is a direct contradiction, so the description does not transparently disclose the destructive nature. Annotation Contradiction.

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

  Conciseness5/5

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

  Four short sentences front-load the core purpose, then add defaults and usage guidance. Every sentence earns its place with no wasted words.

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

  Completeness4/5

  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 need not detail return structure; it mentions project_id. It covers the main use case, defaults, and reset edge case. However, the contradiction with destructiveHint slightly undermines overall completeness, but the description itself is contextually sufficient.

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

  Parameters4/5

  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 value by listing defaults (1920×1080, 10s, 30fps, mp4) and explaining the reset behavior for project_id, which goes beyond the schema's description. It does not explain output_dither, but the schema does comprehensively.

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

  Purpose5/5

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

  The description clearly states the tool's purpose: 'Create a new, blank Clipkit project with the given dimensions and duration, and return its project_id.' It distinguishes itself from siblings by explicitly noting it should be 'first when starting a new video' and describes reset behavior.

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

  Usage Guidelines4/5

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

  The description provides clear usage context: 'Call this first when starting a new video' and explains when to pass an existing project_id for reset. It does not explicitly name alternative tools or state when not to use, but the guidance is sufficient for a new project.

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

• get_projectA
  4/5.0
  Behavior3/5

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

  The readOnlyHint annotation already indicates no side effects, and the description aligns with that. It adds value by describing the output as JSON and mentioning the 'current' project, but it does not elaborate on how project selection works or any pagination or snapshot semantics. With annotation coverage, a score of 3 is appropriate — it provides some context but not deep behavioral detail.

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

  Conciseness5/5

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

  The description is two concise sentences, front-loaded with the primary action and followed by immediate use cases. No redundant words, every sentence earns its place.

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

  Completeness4/5

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

  Given a simple read-only tool with one optional param and no output schema, the description adequately covers purpose, output format (JSON), and typical usage. It doesn't explicitly mention the project_id optionality (which is in the schema) or return structure details, but it is sufficiently complete for the tool's simplicity.

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

  Parameters3/5

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

  The input schema has 100% coverage for the single optional project_id, including guidance on when to omit it. The description itself adds no additional parameter-level details, so it does not compensate beyond the schema. Baseline 3 for high schema coverage is correct.

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

  Purpose5/5

  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, with a specific verb ('Return') and resource ('current Clipkit source'). It also distinguishes itself from sibling tools like describe_project (which likely summarizes) and get_schema (which retrieves schemas), making its purpose unambiguous.

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

  Usage Guidelines4/5

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

  The description provides clear use cases: inspect the project, pass to a render pipeline, or compose follow-up edits. It does not explicitly exclude alternatives or name when not to use it, but the guidance is actionable and appropriate for a lightweight read tool, making the context clear.

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

• get_schemaA
  4.1/5.0
  Behavior3/5

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

  The readOnlyHint annotation already declares this is a read-only operation. The description adds that the schema is 'generated from the protocol' and notes size differences ('much smaller'), but does not disclose other behavioral traits like return format or error conditions. Given the annotation coverage, the description adds enough context but not rich detail.

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

  Conciseness5/5

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

  The description is two sentences: the first defines the tool, the second explains invocation options and use case. Every sentence earns its place, there is no redundancy, and the key verb 'Return' is front-loaded.

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

  Completeness5/5

  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 optional parameter, the description covers purpose, invocation patterns, and use case. The lack of an output schema is acceptable since the tool returns a schema, which is self-descriptive. The description is complete for its complexity.

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

  Parameters3/5

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

  The input schema already covers the sole parameter element_type with a description and all enum values. The tool description essentially repeats this with examples ('text', 'shape', 'particles') and the 'much smaller' note, adding minimal new meaning. Since schema coverage is 100%, baseline 3 is appropriate.

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

  Purpose5/5

  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'. This is a specific verb+resource that distinguishes it from sibling tools like read_docs. The additional context 'so you never guess a field' reinforces its purpose.

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

  Usage Guidelines4/5

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

  The description explicitly says 'Use this when authoring with set_project / add_element so you never guess a field', providing a clear use case. It also explains how to use the optional element_type parameter for smaller responses. However, it does not mention when not to use the tool or compare it to alternatives such as read_docs, so it misses the 'when-not' guidance.

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

• delete_elementA
  4.2/5.0
  Behavior4/5

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

  Annotations already mark the tool as destructive (destructiveHint=true). The description adds valuable context: it works on nested elements and imposes a constraint that the project must keep at least one top-level element, going beyond the basic destructive hint.

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

  Conciseness5/5

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

  The description is two sentences with no wasted words. It front-loads the core action ('Delete the element with the given id') and packs scope and constraints efficiently.

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

  Completeness4/5

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

  Given the tool's complexity, the description covers scope, the nesting behavior, and a critical constraint. The presence of an output schema means return values need not be described. Slight gap: no mention of cascading deletion of child elements, but overall sufficient.

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

  Parameters3/5

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

  Schema coverage is 100% with clear descriptions for both id and project_id. The description does not add parameter-specific semantics beyond referencing 'the given id', so the baseline of 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the tool deletes an element by id, specifies the scope (anywhere in the tree, including nested inside groups or masks), and distinguishes it from sibling tools like add_element and edit_element.

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

  Usage Guidelines4/5

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

  Provides clear context that this is a deletion operation on an existing composition, but doesn't explicitly mention when not to use it or name alternatives; no exclusions are stated.

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

• open_in_editorA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=false and openWorldHint=true. The description adds context that the project is validated before creating the link, that it returns a URL, and that no rendering occurs, which goes beyond the annotation-provided safety hints.

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

  Conciseness5/5

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

  The description is three short sentences with no filler. The main action comes first, the scope/alternative clarification is second, and the return value is last. Every sentence earns its place.

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

  Completeness5/5

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

  For a simple one-parameter tool with an output schema, the description covers usage timing, alternative tool, behavioral nuance (no render), and return value. It is complete enough for an agent to decide when and how to invoke.

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

  Parameters3/5

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

  The input schema already provides a complete description for project_id, including allowed origins and guidance on omitting it for a single local project. 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.

  Purpose5/5

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

  The description uses a specific verb ('create') and resource ('link that opens it in the Clipkit web editor') and explicitly distinguishes from render_video by stating 'nothing is rendered — that's render_video'. This clearly separates it from sibling tools.

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

  Usage Guidelines5/5

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

  It states when to use the tool ('Use after composing or editing') and explicitly names render_video as the alternative for rendering, providing clear guidance on tool selection.

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

• preview_stillA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds valuable context about cost (FREE vs. render_video credits), return format (PNG image), and the ability to sample different time points. This goes beyond the annotations without contradiction.

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

  Conciseness5/5

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

  The description is concise: four sentences that front-load the core action and include all essential information. Every sentence contributes practical guidance (output, reason, cost, parameter default) with no wasted words.

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

  Completeness5/5

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

  The description covers purpose, usage frequency, cost, return format, and parameter behavior. Combined with rich annotations and a complete schema, it leaves no important gaps for an AI agent to make an informed invocation.

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

  Parameters3/5

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

  Schema coverage is 100%, so the description adds marginal value. It reiterates that 'time' is in seconds and defaults to 0, which is already in the schema. It doesn't introduce new parameter semantics, but it does reinforce the usage context for time.

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

  Purpose5/5

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

  The description clearly states a specific verb and resource: 'Render a single frame of the current project to a PNG and return it as an image'. It distinguishes itself from render_video by emphasizing single-frame output and explicitly mentions return format. This makes the tool's purpose unambiguous.

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

  Usage Guidelines5/5

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

  Provides explicit when-to-use guidance: 'This is how you check your work', 'Use it liberally', and specifies the appropriate moments (after composing/edits, at different times to inspect motion). It also contrasts with render_video by noting stills are free, clarifying when not to use the sibling tool.

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

• transcribe_to_captionsA
  4.5/5.0
  Behavior4/5

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

  Discloses behavior beyond annotations: runs Whisper in the server process without API key or third-party upload, requires ffmpeg, and by default adds to the current project unless add:false. It also explains the layer default behavior. These are valuable context traits not present in the sparse annotations. Minor gaps remain, such as expected runtime or return format, but output schema covers return shape.

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

  Conciseness5/5

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

  Five sentences, each with a distinct purpose: purpose, rationale, input modes, prerequisite, and default behavior. No redundant or filler content, and the most important information is front-loaded. The structure is crisp and scannable.

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

  Completeness5/5

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

  For a 7-parameter tool with an output schema and minimal annotations, the description covers purpose, why this tool is needed, execution details, prerequisites, parameter flexibility, and side effects. It is complete enough for an agent to reliably select and invoke it without additional lookups.

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

  Parameters4/5

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

  Schema description coverage is 100%, giving a baseline of 3. The description adds meaning beyond the schema by explaining the practical use cases for url vs path (chat-mode vs local), the layer stacking fallback, and model selection guidance ('tiny.en' for speed, 'small' for accuracy). This context is genuinely helpful for selecting parameters.

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

  Purpose5/5

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

  The description clearly states the action and resource: 'Transcribe an audio or video file into a word-timestamped caption element.' It uses a specific verb and resource, and distinguishes this tool from generic siblings (like add_element) by emphasizing that only this tool provides real per-word timings via speech-to-text.

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

  Usage Guidelines4/5

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

  Provides explicit context for when to use URL vs local path ('use this in chat-mode, where there is no local file'), notes the ffmpeg prerequisite, and explains the add:false option to avoid modifying the project. However, it does not explicitly name alternatives like add_element for non-transcribed captions, so it misses a clear exclusion statement.

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

• create_promoA
  4.7/5.0
  Behavior4/5

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

  Annotations already flag readOnlyHint=false and destructiveHint=true; the description adds valuable context about baking in camera/glass/motion blur, returning an editor link, and being a fast constrained path. It doesn't detail destructive side effects, but annotations cover that. No contradiction.

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

  Conciseness5/5

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

  The description is long but every sentence is productive: it opens with the core function, contrasts with set_project, then gives a structured scene-type rundown. Despite length, it is well-organized and free of fluff.

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

  Completeness5/5

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

  It covers purpose, when to use, when not to use, alternatives, scene types, theme recommendations, and output behavior. Given the tool's complexity and rich schema, this is a complete and sufficient description.

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

  Parameters4/5

  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 providing a per-scene-type cheat-sheet (e.g., hero requires wordmark, showcase requires screenshot URL) and notes the 'mux' theme for data scenes, adding design intent beyond the schema.

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

  Purpose5/5

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

  The description clearly states the tool assembles designed promos/intros/data videos from Clipkit scenes, given an ordered list of scenes and words, and returns an editor link. It explicitly contrasts with set_project for original work, distinguishing it from siblings.

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

  Usage Guidelines5/5

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

  It explicitly says this is a FAST option for conventional promo structures, NOT the default, and directs users to set_project for full creative range. It also provides concrete guidance to mix scene types, avoid forcing hero/cta, and gives example video structures.

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

• describe_projectA
  4.7/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint=true, and the description adds meaningful behavioral context: it returns a compact summary (not full JSON), includes specific content like render-time warnings and paint order, and notes performance characteristics ('Much cheaper to read'). No contradiction with annotations; the description enriches understanding of the tool's behavior.

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

  Conciseness5/5

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

  The description is two sentences, with the first sentence stating purpose and content, the second providing comparison and use case. Every clause adds value, no redundancy, and it is front-loaded with the core function.

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

  Completeness5/5

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

  For a simple tool with one optional parameter and no output schema, the description is complete: it states what the tool returns, what it includes, when to use it, and how it compares to a sibling. The output is a human-readable summary, so a detailed return schema is not necessary, and the description covers all important contextual aspects.

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

  Parameters3/5

  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 any parameter-specific semantics beyond what the schema already provides (e.g., project_id optional, omit for local project). It neither clarifies nor obscures parameter usage, so the baseline is appropriate.

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

  Purpose5/5

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

  The description states a specific verb ('Return') and resource ('a compact, human-readable summary of the current project'), and enumerates exactly what the summary includes (dimensions, fps, duration, element breakdown, per-track timeline, render-time warnings). It also distinguishes from sibling tool get_project by explicitly contrasting with 'get_project's full JSON', 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.

  Usage Guidelines5/5

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

  The description gives explicit when-to-use guidance: 'Much cheaper to read than get_project's full JSON; use it to orient yourself or sanity-check structure without dumping the whole source.' It names the alternative (get_project) and explains the trade-off, which is clear usage guidance beyond a simple 'use this to get a summary.'

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

• load_projectA
  4.7/5.0
  Behavior4/5

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

  Annotations declare readOnlyHint=false and destructiveHint=true. The description adds that loading makes the project 'the current project' and returns project_id, which is useful context. No contradiction.

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

  Conciseness5/5

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

  Two sentences, front-loaded with action and input format; the example URL and round-trip note are valuable and not redundant.

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

  Completeness5/5

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

  Given the output schema and annotations, the description covers input formats, return value, and relationship to open_in_editor, making it fully contextual.

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

  Parameters4/5

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

  Schema coverage is 100%, but the description adds clarity by explaining that omitting project_id loads into a new one, a meaningful semantic beyond the schema's generic 'omit when working on a single local project.'

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

  Purpose5/5

  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', states it returns project_id, and explicitly positions itself as the 'round-trip for open_in_editor,' distinguishing it from sibling tools.

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

  Usage Guidelines5/5

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

  Provides an explicit use case: 'continue working on a project the user opened in the editor or shared earlier' and names the sibling counterpart open_in_editor as its inverse, giving an alternative. It also clarifies behavior with optional project_id.

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

• read_docsA
  4.7/5.0
  Behavior4/5

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

  The readOnlyHint annotation already signals a safe read operation; the description adds context beyond that—each topic's approximate size, the nature of the pattern cards, and the rationale for exposing docs as a tool. It doesn't cover errors or pagination, but for a single-parameter read-only doc fetcher, the added behavioral context is sufficient.

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

  Conciseness4/5

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

  The description is long but tightly packed with necessary distinctions for seven topics; it front-loads the core return behavior and uses semicolon-delimited sub-clauses to keep structure scannable. Slightly verbose but every clause earns its place given the many options.

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

  Completeness5/5

  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 enum parameter and no output schema, the description covers the full set of topics, their relative sizes, recommended usage, and even the rationale for the tool's existence. It is complete for both selection and invocation.

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

  Parameters5/5

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

  While the schema provides an enum and default, the description gives deep semantic meaning to every enum value: sizes, use cases, and distinctions (e.g., 'card' vs 'agents' vs 'protocol'). This far exceeds the schema's bare 'Which doc' description, making the parameter's effect crystal clear.

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

  Purpose5/5

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

  The description opens with a clear verb+resource: 'Return a canonical Clipkit doc as text.' It then enumerates distinct topics and their contents, distinguishing this read-only documentation tool from the sibling project/element tools. The purpose is unambiguous and specific.

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

  Usage Guidelines5/5

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

  Provides explicit when-to-use guidance for each topic: the card is 'the recommended context for authoring', patterns are to 'load ONE alongside the card when the brief matches its archetype', and the full guide is 'fetch only when the card doesn't cover a need'. Also explains that resources may not be model-readable, positioning this tool as the preferred access path.

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

• render_videoA
  4.7/5.0
  Behavior5/5

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

  Annotations only indicate non-read-only and non-destructive; the description adds crucial behavioral details: it validates the project, consumes render credits, requires an API key, runs synchronously, and returns a downloadable URL. These go well beyond the structured annotations.

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

  Conciseness5/5

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

  Three sentences, front-loaded with the core action and outcome, followed by cost/alternative, then performance characteristics. Every sentence earns its place; no fluff.

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

  Completeness5/5

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

  Even with an output schema present, the description covers validation, cost, auth, synchronous behavior, and an alternative tool. It gives the agent all necessary context to decide whether to use this tool and what to expect.

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

  Parameters3/5

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

  Schema covers 100% of parameters with detailed descriptions (resolution enum, project_id omission rule). The description adds the 'validates' and 'current project' framing but doesn't materially extend parameter semantics beyond what the schema already provides. Baseline 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the tool renders the current project to a download-ready MP4 on Clipkit's servers, distinguishing it from siblings like open_in_editor and preview_still. The verb 'render' and specific resource 'current project' make 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.

  Usage Guidelines5/5

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

  Explicitly says this is the paid path, mentions open_in_editor as a free alternative, and notes the need for CLIPKIT_API_KEY. It also warns about synchronous, potentially slow rendering, giving clear context on when to choose this over alternatives.

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

• validate_projectA
  4.7/5.0
  Behavior5/5

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

  Beyond the readOnlyHint annotation, the description details what warnings are surfaced (emoji/non-ASCII, elements past composition end, missing duration) and that they appear even when the JSON is valid. This is valuable behavioral context for an agent.

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

  Conciseness5/5

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

  The description is compact but information-dense, front-loading the primary action and then listing specific warning types and usage guidance. Every sentence contributes unique value.

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

  Completeness5/5

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

  The description fully covers purpose, behavior, and usage context; an output schema exists to handle return values. It is complete given the tool's complexity and annotations.

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

  Parameters3/5

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

  The input schema's description for project_id is thorough, including when to omit it, and coverage is 100%. The tool description adds no additional parameter semantics, so baseline 3 is appropriate.

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

  Purpose5/5

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

  The description explicitly states the tool's function: running the @clipkit/protocol validator and surfacing render-time warnings even when the JSON is valid. It distinguishes itself from describe_project by noting that tool is for a fuller timeline read-back, so purpose is unambiguous.

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

  Usage Guidelines5/5

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

  It gives explicit temporal guidance ('Run it before you share or render the project') and names the alternative (describe_project) for different needs. This clearly answers when to use versus siblings.

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

• set_projectA
  4.9/5.0
  Behavior5/5

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

  Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description adds validation behavior ('validated against the @clipkit/protocol before being accepted'), error behavior ('invalid inputs return an error'), and unknown-key handling ('flags any it does not recognize'). These operational details give the agent expectations for side effects and failure modes.

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

  Conciseness5/5

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

  The description is robust but every sentence earns its place: core action, primary usage, alternatives, id behavior, validation, shape summary, and schema pointer. It is front-loaded with the most important information and structured logically.

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

  Completeness5/5

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

  Given the nested object structure and presence of an output schema, the description is exceptionally complete. It covers operation, when to use, parameter behavior, validation, and unknown-key handling. Return values are not described but that is covered by the output schema.

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

  Parameters4/5

  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 compensates by explaining the source shape ('{ width, height, duration, ... elements:[…] }') and project_id semantics ('Pass an existing project_id to replace that project; omit it to create a new one'). It also points to get_schema for exact fields, adding guidance without replacing schema.

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

  Purpose5/5

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

  Description opens with 'Replace the entire project with the given source JSON, returning its project_id,' a specific verb+resource statement. It distinguishes itself from sibling tools by declaring 'This is the PRIMARY way to build' and contrasting with edit_element/add_element/delete_element for single-element tweaks.

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

  Usage Guidelines5/5

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

  Explicitly states when to use ('to create a composition or to add/change many elements at once') and when not to ('To tweak a single element in an existing project, use edit_element / add_element / delete_element instead'). Also clarifies project_id behavior: pass to replace, omit to create new.

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

• add_elementA
  5/5.0
  Behavior5/5

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

  Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description explains key behavioral aspects: the element is validated as part of the whole project before being added, and unrecognized keys are flagged. This gives the agent insight into error handling and validation behavior, which is not evident 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.

  Conciseness5/5

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

  The description is concise yet information-dense. Each sentence serves a purpose: the first defines the core function, the second explains default vs nested behavior, the third lists supported element types, the fourth differentiates from set_project, the fifth describes validation, and the sixth directs to get_schema. No filler or redundancy.

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

  Completeness5/5

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

  Given the tool's complexity (nested element object, three parameters, an output schema exists), the description is comprehensive. It covers all essential aspects: purpose, placement behavior, supported element types, alternative tools, validation, and parameter semantics. The reference to get_schema handles per-type fields, and the output schema renders return-value documentation unnecessary. No significant gaps remain.

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

  Parameters5/5

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

  The input schema already has 100% coverage with descriptions for all parameters, but the tool description adds meaningful value by explaining the semantics of parent_id (top level vs. nested) and project_id (omitted for single local project). It also clarifies that the element must include a type and is a valid schema element, enriching the structured data with context that aids correct parameter construction.

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

  Purpose5/5

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

  The description clearly states the tool's purpose: 'Append a single element to an existing project.' It specifies the resource (project) and action (add element), and distinguishes itself from set_project by noting that set_project is for creating compositions or adding multiple elements at once. This makes the purpose unambiguous and well-differentiated from siblings.

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

  Usage Guidelines5/5

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

  The description provides explicit usage guidance: it notes that by default the element is added at the top level, and parent_id is used to nest it into a group. It also gives a clear alternative: 'To create a composition or add several elements at once, build the JSON and use set_project instead.' Furthermore, it advises calling get_schema(element_type) for exact fields, giving the agent actionable paths for correct usage.

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

• edit_elementA
  5/5.0
  Behavior5/5

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

  The description discloses important behavioral traits: merge semantics (only provided keys change), null to remove a key, id can target any element anywhere in the tree (including nested in groups or masks), and the result is re-validated before acceptance. The annotations provide basic readOnly/destructive hints, but the description adds crucial operational detail without contradicting them.

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

  Conciseness5/5

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

  The description is four sentences with no unnecessary words. It front-loads the core action and then efficiently covers scope, removal semantics, an alternative usage, and validation, with every sentence earning its place.

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

  Completeness5/5

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

  Given the tool's complexity (3 params, nested object, output schema exists), the description is fully complete. It covers purpose, scope, parameter behavior, alternative tools, and validation, while the output schema handles return value details.

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

  Parameters5/5

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

  The description significantly enriches parameter understanding beyond the schema. It explains that patch replaces whole nested values (e.g., keyframe_animations) and that null removes keys, and it clarifies that id can be any element anywhere in the tree. Even though schema coverage is 100%, the description adds critical usage nuances and an example.

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

  Purpose5/5

  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 by merging in a partial element, making it distinct from add_element, delete_element, and set_project. The title 'Tweak one existing element (merge changed fields)' reinforces this specific purpose.

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

  Usage Guidelines5/5

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

  It explicitly states this is for tweaking an existing composition and directs to set_project for creating a composition or changing many elements at once, providing clear when-to-use guidance and an alternative. The context of editing an existing element vs. creating/deleting is also implied.

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