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

With no annotations provided, the description carries full burden. It discloses key behavioral traits: the tool saves changes to the project file, reuses existing text tracks or creates new ones, and includes detailed positioning reference. However, it lacks information on permissions, error conditions, or what happens if the project file is invalid.

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 and front-loaded with the core functionality in the first sentence. The positioning reference is necessary but presented efficiently. No wasted sentences, though the coordinate explanation could be slightly more integrated.

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

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

For a complex tool with 13 parameters, no annotations, and no output schema, the description is moderately complete. It covers the core operation and positioning details but lacks information on return values, error handling, or integration with sibling tools like 'read_project' or 'render_preview'.

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 significant value by explaining the coordinate system for x and y parameters with clear examples (-1 to 1 range, canvas center at 0,0), which goes beyond the schema's basic descriptions. This compensates well for the high parameter count.

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 specific action ('Add a new text overlay'), the target resource ('to the project'), and the outcome ('and save'). It distinguishes from siblings like 'update_segment' or 'delete_segment' by specifying creation of text overlays rather than modifying or removing existing segments.

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 for adding text overlays to projects, but provides no explicit guidance on when to use this tool versus alternatives like 'update_segment' for modifying existing text or other media tools. The mention of reusing existing text tracks offers some contextual hint but no clear when/when-not rules.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: it creates animations ('Creates smooth zoom in/out effects'), specifies interpolation method ('The zoom animation interpolates linearly between keyframes'), and clarifies timing ('Keyframes are relative to the segment's start time'). This covers essential aspects like mutation effects and operational details, though it could mention potential side effects like file modifications.

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 and front-loaded, starting with the core purpose and followed by illustrative examples and technical details. Every sentence earns its place by enhancing understanding without redundancy, making it efficient and well-structured for quick comprehension.

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 (adding animations with keyframes), no annotations, and no output schema, the description is largely complete. It explains what the tool does, how it behaves, and provides usage examples. However, it lacks details on output (e.g., what is returned after adding keyframes) and error handling, which could improve completeness for a mutation tool.

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

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

Schema description coverage is 100%, so the schema already documents all parameters (path, segment_id, keyframes) thoroughly. The description adds minimal value beyond the schema, such as clarifying scale values in examples (e.g., '1.2 = 20% zoom in'), but does not provide significant additional semantics. This meets the baseline of 3 for high schema coverage.

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 purpose with specific verbs ('add scale/zoom animation keyframes') and resources ('to a video segment'), distinguishing it from siblings like 'add_text_segment' or 'update_segment' by focusing on zoom effects. It explicitly mentions creating 'smooth zoom in/out effects,' which is distinct from other tools that handle text, analysis, or deletion.

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

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

The description provides clear context through examples (e.g., 'zoom in 20% for the hook'), implying usage for adding zoom animations to video segments. However, it does not explicitly state when not to use this tool or name alternatives among siblings, such as 'update_segment' for other modifications, leaving some guidance implicit rather than explicit.

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

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

No annotations are provided, so the description carries the full burden. It describes the tool's dual-mode behavior (returning unanalyzed clips initially, then saving metadata on subsequent calls) and mentions the managed library path, which adds some context. However, it lacks details on permissions, rate limits, error handling, or what 'unanalyzed' means operationally, leaving significant behavioral gaps for a mutation tool.

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

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

The description is appropriately sized with three sentences that are front-loaded with the core purpose. Each sentence adds value: the first states the action, the second explains the two-step workflow, and the third clarifies the convenience aspect. There's no wasted text, though it could be slightly more structured for a 5.

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

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

Given 3 parameters, no annotations, and no output schema, the description is moderately complete. It covers the purpose and usage workflow but lacks details on behavioral traits like side effects, return values, or error conditions. For a tool with mutation capabilities (implied by saving metadata) and no structured safety hints, this leaves room for improvement.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds minimal value beyond the schema: it implies that 'clip_id' is optional and that 'metadata' is used for saving analysis results, but doesn't provide additional semantics like format examples or constraints. This meets the baseline of 3 when schema coverage is high.

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 purpose: analyzing clips in Statonic's app library and returning unanalyzed clips for Claude to analyze. It specifies the verb 'analyze' and resource 'clips in Statonic's app library', but doesn't explicitly differentiate from sibling tools like 'analyze_video_clip' or 'search_statonic_library', which is why it doesn't reach a 5.

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

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

The description provides clear context on when to use this tool: for analyzing the app's managed clip library without specifying full paths. It mentions calling it again with metadata to save after analysis, which implies a workflow. However, it doesn't explicitly state when not to use it or name alternatives among siblings, so it falls short of a 5.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It describes the tool's actions (extraction, analysis, saving) and mentions Claude's role, but lacks details on permissions, error handling, or performance characteristics like rate limits. It adequately covers the core behavior without rich 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 with three sentences that each add value: stating the tool's purpose, outlining the process, and providing usage context. It is front-loaded with the core functionality and avoids unnecessary repetition, though it could be slightly more streamlined.

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 (4 parameters, no output schema, no annotations), the description is moderately complete. It explains the tool's purpose and process but lacks details on output format, error cases, or integration with Claude. It is adequate but has clear gaps for a tool with this level of functionality.

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

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

Schema description coverage is 100%, so the schema fully documents all parameters. The description adds no additional parameter semantics beyond what's in the schema, such as explaining the purpose of 'category' or 'keyframe_count' in more detail. Baseline 3 is appropriate as the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose with specific verbs ('extract keyframes', 'returns frames', 'saves metadata') and resources ('video clip', 'images', 'JSON file'). It distinguishes from siblings by focusing on analysis and metadata generation rather than operations like adding segments or searching libraries.

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 context for when to use the tool ('to understand what's in a clip before selecting it for a project'), but does not explicitly state when not to use it or name specific alternatives among the sibling tools. This gives adequate guidance without full exclusion criteria.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly describes the tool's behavior: it reads from 'variation-context.json', writes output files to a variations folder, applies text changes and clip overrides, and specifies that the editor handles subsequent steps automatically. It also mentions prerequisites and post-call restrictions, covering operational context effectively.

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

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

The description is well-structured and front-loaded with the core purpose, followed by important usage notes and implementation details. However, it includes some redundancy (e.g., repeating 'IMPORTANT' sections) and could be slightly tightened without losing clarity, preventing a perfect score.

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 (generating project variations with multiple operations), no annotations, and no output schema, the description is highly complete. It covers prerequisites, input semantics, behavioral steps, file I/O details, and post-call instructions, providing all necessary context for an agent to use the tool correctly without additional documentation.

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 description coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema: it explains that variations are 'full copies of the project' and details how 'textChanges' and 'clipOverrides' are applied (e.g., 'find/replace rules applied to ALL text segment "text" fields (case-insensitive)' and 'swap specific video segments by segmentId'). This enhances understanding but doesn't fully elevate to a 5, as it doesn't clarify edge cases or advanced usage.

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 purpose: 'Generate project variation files from the currently open project's variation session.' It specifies the verb ('generate'), resource ('project variation files'), and source ('variation session'), distinguishing it from siblings like 'write_statonic_project' or 'render_preview' that handle different operations.

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

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

The description provides explicit usage instructions: 'Do NOT call get_reference_frames or any other tool before this one. Go straight to create_variations' and 'After calling create_variations, do NOT call write_statonic_project, render_preview, get_suitable_audio, or any other tool.' It names specific tools to avoid and explains the required context (user must have clicked 'Variations' in the editor toolbar).

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool deletes and saves, which implies a destructive, persistent mutation. However, it doesn't mention permissions required, whether deletion is reversible, what happens to associated data, error conditions, or confirmation prompts. For a destructive operation with zero annotation coverage, this is insufficient.

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 extremely concise—just one sentence with seven words. It's front-loaded with the core action ('Delete a segment') and efficiently adds context ('from the project and save'). There's no wasted verbiage or redundancy, making it easy to parse quickly.

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 this is a destructive mutation tool with no annotations and no output schema, the description is incomplete. It doesn't cover error handling, return values, side effects, or safety considerations. The context signals indicate two required parameters, but the description doesn't explain their interplay or typical usage patterns, leaving significant gaps for an agent.

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

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

Schema description coverage is 100%, so the schema fully documents both parameters (path and id). The description doesn't add any parameter-specific details beyond what the schema provides, such as format examples or constraints. However, it implies the tool operates on a project file and a segment ID, which aligns with the schema but doesn't enhance it.

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

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

The description clearly states the action ('Delete a segment') and the resource ('from the project'), which is specific and unambiguous. However, it doesn't distinguish this tool from its sibling 'update_segment', which could also modify segments. The phrase 'and save' adds useful context about persistence but doesn't fully differentiate the tool's unique purpose.

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

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

The description provides no guidance on when to use this tool versus alternatives like 'update_segment' or other segment-related tools. It mentions saving, which implies a write operation, but doesn't specify prerequisites, constraints, or typical use cases. There's no explicit when-to-use or when-not-to-use information.

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

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

With no annotations provided, the description carries the full burden. It discloses that the tool generates '5 high-quality hook text options' and uses 'proven formulas,' but lacks details on behavioral traits like error handling, rate limits, or authentication needs. It doesn't contradict annotations, but offers only basic 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 front-loaded and concise with three sentences that each add value: stating the purpose, output format, and usage timing. There's no wasted text, and it efficiently communicates key information without redundancy.

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

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

Given the tool's moderate complexity (2 parameters, no output schema, no annotations), the description is fairly complete. It covers purpose, usage context, and output readiness, but lacks details on behavioral aspects like error cases or performance limits, which would be helpful for a generation tool with no output schema.

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

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

Schema description coverage is 100%, so the schema fully documents the two parameters ('topic' and 'count'). The description adds no additional parameter semantics beyond implying 'count' defaults to 5, which is already in the schema. This meets the baseline for high schema coverage.

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 purpose with specific verbs ('Generate 5 high-quality hook text options') and resources ('for a given topic, using proven formulas from hook-knowledge.json'). It distinguishes from siblings by specifying it's for hook text generation, unlike tools like 'analyze_video_clip' or 'get_suitable_audio' that handle different tasks.

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: 'Call this before creating any project to get the best hook text.' This tells the agent when to use this tool (as a preparatory step) and implies it's not for other contexts like analysis or editing, though it doesn't name specific alternatives.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds useful context about automatic account usage and return format details (path, duration, dimensions), which goes beyond the basic 'get' operation. However, it doesn't mention potential limitations like pagination, rate limits, error conditions, or whether this is a read-only operation (though 'get' implies it).

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 with two sentences that efficiently convey purpose, automatic behavior, and return format. It's front-loaded with the core functionality. The second sentence could potentially be merged for even tighter structure, but overall it's concise with minimal waste.

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

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

For a single-parameter read operation with no output schema, the description provides adequate coverage of what the tool does and what it returns. However, it lacks details about the return structure (e.g., array format, pagination), error handling, or authentication requirements beyond the automatic account usage. The absence of annotations means more behavioral context would be helpful.

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

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

Schema description coverage is 100%, with the single parameter 'category' fully documented in the schema with enum values. The description adds marginal value by listing the categories in parentheses, but doesn't provide additional semantic context beyond what's already in the schema. This meets the baseline for high schema coverage.

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 purpose: 'Get clips from Statonic library filtered by category' with specific categories listed. It distinguishes from siblings like 'search_clip_bank' or 'search_statonic_library' by focusing on category filtering rather than general search. However, it doesn't explicitly differentiate from 'analyze_statonic_library' or 'index_clip_bank', which prevents a perfect score.

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 by mentioning 'filtered by category' and 'currently active account', suggesting this is for retrieving clips when you know the specific category needed. However, it doesn't provide explicit guidance on when to use this versus alternatives like 'search_clip_bank' or 'search_statonic_library', nor does it mention any prerequisites or 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?

With no annotations provided, the description carries the full burden and does well by disclosing key behavioral traits: frames are scaled to 640px wide, there's a limit of ≤6 frames per call for speed, and it returns images that Claude can see and describe. It does not mention error handling, file format support, or performance beyond speed, but covers essential operational constraints.

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 with three sentences, each adding value: the first states the core purpose, the second gives usage context, and the third provides important constraints. It is front-loaded with the main function and wastes no words.

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

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

Given the tool's moderate complexity (2 parameters, no output schema, no annotations), the description is fairly complete: it covers purpose, usage, key constraints, and output format. However, it lacks details on error cases, supported video formats, or exact return structure, which could be useful for an agent. No output schema exists, so some gaps remain.

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

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

Schema description coverage is 100%, so the schema already documents both parameters thoroughly. The description adds some context by mentioning the max of 6 frames for 'times_sec', but does not provide additional meaning beyond what the schema specifies for 'video_path' or timestamp details. Baseline 3 is appropriate as the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose with specific verbs ('extract frames', 'return as images') and resources ('from a video file'), and distinguishes it from siblings like 'get_video_info' or 'get_reference_frames' by focusing on frame extraction rather than metadata or reference frames. It explicitly mentions what the tool does and what it returns.

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 context for when to use this tool ('to visually inspect video content') and mentions Claude's ability to describe frames, but it does not explicitly state when not to use it or name alternatives among siblings. It implies usage for visual inspection rather than other video analysis tasks.

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

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

With no annotations provided, the description carries the full burden. It discloses that this is a read operation ('Read... and return') and describes the workflow context, but doesn't mention potential behavioral aspects like error conditions, rate limits, authentication needs, or what happens if no pending request exists. It adds some context but leaves gaps.

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 perfectly concise with two sentences that each earn their place: the first explains what the tool does, the second explains when to use it and what to do next. There's zero wasted text and it's front-loaded with the core functionality.

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 zero parameters, no annotations, and no output schema, the description provides good context about the workflow and sequencing. However, it doesn't describe the return format (frames as images) in detail or mention potential edge cases. For a read-only tool with this complexity level, it's mostly complete but could benefit from slightly more behavioral detail.

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

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

The tool has 0 parameters with 100% schema description coverage, so no parameter documentation is needed. The description appropriately doesn't discuss parameters, maintaining focus on the tool's purpose and usage. A baseline of 4 is appropriate for zero-parameter tools.

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 specific action ('Read the pending reference video analysis request and return each scene frame as an image for you to analyze') and distinguishes it from siblings like 'get_frames' by specifying it's for reference video analysis requests triggered by user actions. It provides a complete verb+resource+scope combination.

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

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

The description explicitly states when to use this tool ('After the user clicks "Copy Reference" in the editor and selects a video, call this tool') and what to do next ('Then call write_reference_result with your analysis'). It provides clear sequencing and alternative guidance by naming the follow-up tool.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the tool's logic ('calculates exact audio positioning so the drop hits at the transition point') and output behavior ('returns audios where...'), but lacks details on permissions, rate limits, or error handling, which are important for a tool that filters and returns data.

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 with three sentences that are front-loaded with the core purpose. Each sentence adds value by explaining functionality, output, and usage context, though it could be slightly more streamlined by combining some ideas.

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 moderate complexity (3 parameters, no output schema, no annotations), the description is somewhat complete but has gaps. It explains the tool's purpose and usage well, but lacks details on output format, error cases, or integration with sibling tools, which would enhance completeness for a filtering tool.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal value by implying the parameters relate to timing requirements, but does not provide additional syntax, format details, or examples beyond what the schema specifies, meeting the baseline for high coverage.

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 purpose with specific verbs ('find audio tracks') and resources ('audio tracks suitable for a video project'), and distinguishes it from sibling tools by focusing on audio selection based on timing requirements, unlike tools like 'get_clips_by_category' or 'search_statonic_library' which handle different resources or criteria.

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 context for when to use this tool ('when creating projects that need audio synced to clip transitions'), but it does not explicitly state when not to use it or name specific alternatives among the sibling tools, such as 'search_statonic_library' which might handle broader audio searches.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the method ('via ffprobe') but lacks details on permissions needed, error handling (e.g., invalid paths), rate limits, or output format. For a tool with zero annotation coverage, this leaves significant gaps in understanding its operational behavior.

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

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

The description is a single, efficient sentence that front-loads the core purpose ('Get width, height, and duration') and method ('via ffprobe'), with zero wasted words. It is appropriately sized for a simple tool with one parameter.

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 low complexity (1 parameter, no output schema, no annotations), the description is minimally complete. It states what the tool does but lacks details on output structure, error cases, or integration context, which could help an agent use it more effectively despite the simplicity.

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

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

Schema description coverage is 100%, with the single parameter 'video_path' documented as 'Absolute path to the video file'. The description adds no additional parameter semantics beyond this, such as format requirements or examples, so it meets the baseline for adequate but not enhanced coverage.

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 specific action ('Get') and the exact resources returned ('width, height, and duration of a video file'), using the technical method 'via ffprobe'. It distinguishes itself from siblings like 'get_frames' or 'get_clips_by_category' by focusing on metadata extraction rather than content retrieval or filtering.

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

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

No explicit guidance is provided on when to use this tool versus alternatives. While it implies usage for obtaining video metadata, it doesn't specify prerequisites (e.g., file accessibility), exclusions (e.g., unsupported formats), or direct alternatives among siblings like 'analyze_video_clip', leaving the agent to infer 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It describes key behaviors: recursive scanning, metadata generation for clips without it, and file creation/updates ('Creates/updates index.json'). However, it lacks details on permissions, error handling, performance (e.g., time/rate limits), or what 'analyze' entails (e.g., formats supported).

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 in the first sentence, followed by supporting details. Every sentence adds value: the first explains the main action, the second clarifies metadata handling, and the third specifies the output file. 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?

For a tool with 2 parameters, no annotations, and no output schema, the description is moderately complete. It covers the tool's purpose and key behaviors but lacks details on output format (beyond 'index.json'), error cases, or integration with siblings. Given the complexity of video analysis, more context on limitations or results would be helpful.

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 parameters are fully documented in the schema. The description adds no additional semantic context beyond implying 'folder_path' is for the clip bank and 'regenerate' controls re-analysis. This meets the baseline for high schema coverage without compensating 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's purpose with specific verbs ('scan', 'analyze', 'build', 'generate', 'create/update') and resources ('folder', 'video clips', 'searchable index', 'metadata', 'index.json'). It distinguishes from siblings like 'search_clip_bank' (which queries an existing index) by emphasizing index creation/updating.

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 for indexing video clips in a folder, but provides no explicit guidance on when to use this versus alternatives like 'analyze_video_clip' (single clip analysis) or 'search_clip_bank' (querying). No exclusions or prerequisites are mentioned, leaving usage context inferred rather than stated.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It describes the action (analyze video, extract hook formula/text, append to JSON file) and the purpose (build knowledge base), but lacks details on permissions needed, rate limits, error handling, or what 'hook formula' entails. It doesn't contradict annotations, but could provide more 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 efficiently structured in two sentences: the first states the core functionality, and the second provides usage guidance. Every sentence adds value without redundancy, making it appropriately sized and front-loaded.

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

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

Given the tool's complexity (analyzing video content and updating a knowledge base), no annotations, and no output schema, the description is minimally adequate. It explains the purpose and outcome, but lacks details on behavioral traits, error cases, or output format, leaving gaps for an AI agent to infer.

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 has 100% description coverage for its single parameter ('video_path'), so the baseline is 3. The description doesn't add any parameter-specific details beyond what's in the schema (e.g., no format constraints or examples for 'video_path'), but it doesn't need to compensate for gaps.

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 purpose: 'Analyze a trending video file to extract its hook formula and text. Appends the learned example to hook-knowledge.json for future use.' It specifies the verb (analyze/extract/append), resource (video file), and outcome (adds to knowledge base). However, it doesn't explicitly differentiate from siblings like 'analyze_video_clip' or 'generate_hook_options' which might have overlapping functionality.

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 some usage context: 'Use this to build up your hook knowledge base from high-performing videos.' This implies it's for learning from successful videos, but it doesn't explicitly state when to use this versus alternatives like 'analyze_video_clip' or 'generate_hook_options', nor does it mention prerequisites or 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?

With no annotations provided, the description carries the full burden. It discloses the return format (id, name, description, slot count) and indicates it's a read operation ('List'), but lacks details on pagination, rate limits, authentication needs, or error conditions. It adds value beyond the schema but doesn't fully cover behavioral traits.

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 a single, efficient sentence that front-loads the core action ('List all available video structure templates') and adds essential return details without redundancy. Every word earns its place, making it highly concise and well-structured.

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 simplicity (0 parameters, no output schema, no annotations), the description is reasonably complete. It specifies the resource, action, and return format. However, it could be more comprehensive by addressing potential limitations like result ordering or availability constraints, slightly reducing completeness.

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

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

The tool has 0 parameters, and schema description coverage is 100%, so no parameter documentation is needed. The description doesn't add parameter semantics, but this is appropriate given the lack of inputs. A baseline of 4 is applied as it meets expectations for a parameterless tool.

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

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

The description clearly states the verb ('List') and resource ('all available video structure templates'), specifying exactly what the tool does. It distinguishes itself from siblings like 'use_template' by focusing on retrieval rather than application, and from 'search_clip_bank' by targeting templates instead of clips.

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 by stating it lists 'available' templates, suggesting it's for selection or browsing purposes. However, it doesn't explicitly mention when to use this versus alternatives like 'search_statonic_library' or 'get_clips_by_category', nor does it provide exclusions or prerequisites for use.

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

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

No annotations are provided, so the description carries full burden. It discloses the return format (human-readable summary plus full JSON) and the read-only nature ('Read'), but lacks details on error handling, file access permissions, or performance considerations. Adequate but with gaps for a tool with no annotation support.

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

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

Two sentences with zero waste: first states purpose and output, second provides usage guidance. Front-loaded with essential information, 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 no annotations, no output schema, and a simple single-parameter input, the description is mostly complete. It covers purpose, output format, and usage context, but could benefit from more behavioral details (e.g., error cases). Good for a read-only tool with 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%, so the schema already documents the 'path' parameter fully. The description adds no additional parameter details beyond what the schema provides, such as file format expectations or path validation rules. Baseline 3 is appropriate when schema does the heavy lifting.

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

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

The description clearly states the verb ('Read') and resource ('Statonic project JSON file'), specifying it returns both a human-readable summary and full JSON. It distinguishes from siblings like 'write_statonic_project' (write operation) and 'analyze_statonic_library' (different resource).

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

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

Explicitly states 'Use this first to understand the project before making edits,' providing clear when-to-use guidance and implying alternatives (e.g., edit tools like 'update_segment'). It effectively directs usage in the workflow 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?

With no annotations provided, the description carries full burden and does well by disclosing key behaviors: it returns a JPEG image, shows canvas layout including subject positions and obstructions, and is intended for preview purposes. It doesn't mention performance characteristics like processing time or file size limits, but covers the essential operational behavior.

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

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

Two well-structured sentences with zero waste. The first sentence defines the tool's purpose and output, the second provides usage guidance. Every word contributes to understanding the tool's function and appropriate use.

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 2 parameters, 100% schema coverage, and no output schema, the description provides excellent context about what the tool does and when to use it. It explains the return format (JPEG image) and the visual information it provides. The only minor gap is not explicitly stating this is a read-only operation, though that's implied by the preview nature.

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

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

Schema description coverage is 100%, so the schema already fully documents both parameters. The description doesn't add any parameter-specific information beyond what's in the schema descriptions. This meets the baseline expectation when schema coverage is complete.

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 specific action ('Render a composite preview frame'), the resource ('project at a specific time'), and the scope ('all video layers cropped and positioned, text overlays drawn on top'). It distinguishes from siblings by focusing on visual preview generation rather than editing or analysis tools.

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

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

Explicitly states when to use this tool: 'Use this before repositioning elements so you can make informed placement decisions.' This provides clear context for usage and distinguishes it from tools that perform actual modifications like update_segment or add_text_segment.

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?

No annotations are provided, so the description carries the full burden. It mentions that the tool 'Returns clip metadata for Claude to rank and select the best matches,' which adds some behavioral context about output format and ranking. However, it doesn't disclose critical traits like whether this is a read-only operation, potential rate limits, authentication needs, or how results are structured (e.g., pagination). For a search tool with zero annotation coverage, this is insufficient.

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 and front-loaded: the first sentence states the core purpose, the second explains the return value, and the third provides usage guidance. Every sentence earns its place with no redundancy or waste, making it highly efficient.

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

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

Given the tool's moderate complexity (search with 3 parameters), no annotations, and no output schema, the description is partially complete. It covers the purpose and hints at output behavior but lacks details on error handling, result format, or integration with sibling tools. Without annotations or output schema, more context is needed for full agent understanding.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters thoroughly. The description adds no additional meaning beyond what the schema provides—it doesn't explain parameter interactions, default behaviors, or usage examples. With high schema coverage, the baseline is 3, and the description doesn't compensate with extra insights.

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 purpose: 'Search the clip bank for clips matching a description.' It specifies the verb ('search') and resource ('clip bank'), and distinguishes it from siblings like 'get_clips_by_category' by emphasizing description-based matching. However, it doesn't explicitly contrast with 'search_statonic_library' or other search tools, preventing a perfect score.

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 implied usage guidance: 'Use this to find the best clip for a specific video segment.' This suggests a context for video editing or content creation. However, it lacks explicit when-to-use vs. alternatives (e.g., 'get_clips_by_category' for category-based retrieval or 'search_statonic_library' for other media), and no exclusions or prerequisites are mentioned.

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

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

With no annotations provided, the description carries the full burden. It discloses that the tool returns 'all analyzed clips with their metadata' and involves 'Claude to rank by relevance', adding useful behavioral context. However, it lacks details on potential limitations like rate limits, authentication needs, or pagination, which are important for a search operation.

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 in the first sentence, followed by two concise sentences that add necessary context without waste. Every sentence earns its place by clarifying the return value and usage intent, making it efficient and well-structured.

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

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

Given the complexity (a search tool with 3 parameters, no output schema, and no annotations), the description is mostly complete. It covers the purpose, return data, and usage context. However, it could improve by mentioning output format or any behavioral constraints, as there's no output schema to rely on.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds no additional parameter semantics beyond implying the query is for 'a specific purpose', which is minimal value. Baseline 3 is appropriate as the schema does the heavy lifting.

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

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

The description clearly states the specific action ('Search Statonic's analyzed clip library'), the resource ('clips'), and the outcome ('for clips matching a query'). It distinguishes from siblings like 'search_clip_bank' by specifying it's for 'analyzed clips' with 'metadata for Claude to rank by relevance', making the purpose distinct and well-defined.

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 context on when to use this tool: 'to find the best clips for a specific purpose' and implies it's for relevance ranking by Claude. However, it does not explicitly state when not to use it or name alternatives (e.g., 'search_clip_bank' or 'get_clips_by_category'), leaving some ambiguity compared to sibling tools.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool updates and saves changes, implying mutation, but lacks details on permissions, error handling, or side effects. The mention of 'partial update' in the schema is not reinforced in the description, leaving behavioral gaps.

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

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

The description is well-structured and front-loaded with the core purpose, followed by organized lists of properties. Every sentence earns its place by providing essential details without redundancy, making it efficient and easy to scan.

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 (mutation with nested objects) and lack of annotations and output schema, the description is incomplete. It covers what properties can be updated but omits critical context like return values, error conditions, or dependencies on tools like 'read_project' for the 'id' parameter.

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 significant value by detailing the semantics of 'patch' parameter properties (e.g., clipX, text, startUs), explaining their ranges and units, which goes beyond the schema's generic 'Key/value pairs' 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 explicitly states the tool's purpose: 'Update one or more properties of an existing segment (video or text) and save.' It specifies the resource (segment), the action (update properties), and distinguishes it from siblings like 'add_text_segment' (creation) and 'delete_segment' (deletion).

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

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

The description provides clear context for usage by listing writable properties for video and text segments, and it mentions an alternative tool ('add_zoom_keyframes') for scaleKeyframes. However, it does not explicitly state when NOT to use this tool or compare it to all relevant siblings like 'create_variations' or 'use_template'.

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?

No annotations are provided, so the description carries the full burden. It discloses key behavioral traits: it's a creation tool (implies mutation), auto-selects clips for unfilled slots, and integrates with a workflow. However, it doesn't mention permissions, rate limits, or what happens on failure (e.g., error handling). For a mutation tool with zero annotation coverage, this is good but not exhaustive.

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 and front-loaded: the first sentence states the core purpose, followed by a numbered workflow that efficiently guides usage. Every sentence earns its place—no redundancy or fluff. The structure is clear and actionable.

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 (creation with auto-selection and overrides), no annotations, and no output schema, the description is largely complete: it explains the purpose, workflow, and parameter intent. However, it lacks details on return values or error cases, which would be helpful for a mutation tool. It compensates well with workflow context but has minor gaps.

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

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

Schema description coverage is 100%, so the schema already documents all parameters (template_id, project_name, slots). The description adds minimal value beyond the schema: it mentions 'slot overrides' and 'auto-selects clips by category for unfilled slots,' which aligns with the schema's description for 'slots.' No additional syntax or format details are provided, 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's purpose: 'Create a Statonic project from a template' with the specific behavior 'Auto-selects clips by category for unfilled slots.' It distinguishes from siblings like 'list_templates' (which lists templates) and 'write_statonic_project' (which writes projects without template context). The verb 'create' and resource 'Statonic project' are specific and 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 workflow guidance: '1. Call list_templates to see available templates 2. Get clips with get_clips_by_category to know what's available 3. Call use_template with slot overrides 4. Verify with render_preview.' This clearly indicates when to use this tool (step 3) versus alternatives like 'list_templates' (step 1) and 'render_preview' (step 4), with prerequisites and sequencing.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: the tool writes analysis results to an editor modal that auto-populates, and it enforces specific text structuring rules (e.g., separating spanning vs. slot-specific text). However, it lacks details on error handling, permissions, or response format, leaving some gaps for a write operation.

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 in the first sentence, followed by essential usage guidelines and text structuring rules. Each sentence adds critical value without redundancy, making it highly efficient and well-structured for quick comprehension by an agent.

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

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

Given the complexity of a write operation with 5 parameters and no annotations or output schema, the description does a strong job by covering purpose, sequencing, and text handling rules. However, it doesn't fully address potential behavioral aspects like error conditions or what happens on success, leaving minor gaps in completeness for a tool with no structured safety or output information.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds some semantic context by explaining the purpose of 'slots' and 'spanning_texts' in the analysis workflow, but it doesn't provide additional syntax or format details beyond what the schema specifies. This meets the baseline for high schema coverage.

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 specific action ('Write your analysis of the reference video frames back to the editor') and resource ('reference video frames'), distinguishing it from siblings like 'get_reference_frames' (which retrieves frames) and 'write_statonic_project' (which writes a different type of project). The purpose is precise and actionable.

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

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

The description explicitly states when to use this tool ('Call this after get_reference_frames'), providing clear sequencing guidance. It also distinguishes usage from alternatives by specifying text placement rules (e.g., use 'spanning_texts' for multi-slot text vs. 'detectedText' for unique slot text), helping the agent choose correctly among related tools.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior by detailing the output (a JSON file), formatting rules, and post-actions (e.g., using render_preview). However, it lacks explicit mention of potential side effects like file overwriting or error handling, which slightly limits transparency.

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 overly verbose and poorly structured, mixing tool purpose with extensive styling rules, hook formulas, and examples that belong in external documentation. It spans multiple sections without clear separation, making it difficult to quickly grasp the core functionality, though the initial sentence is front-loaded.

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

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

Given the complexity of creating a Statonic project with nested objects and no output schema, the description is mostly complete. It includes detailed examples, formatting rules, and integration with other tools (e.g., render_preview), but it could benefit from clarifying error cases or validation requirements for the JSON input.

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

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

Schema description coverage is 100%, so the schema already documents both parameters ('project' and 'filename'). The description adds context by providing an example JSON structure for the 'project' parameter and naming conventions for 'filename', but this is marginal value beyond the schema's baseline documentation.

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

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

The description clearly states the verb 'Write' and the resource 'Statonic project JSON file', making the purpose specific and actionable. It distinguishes from siblings like 'read_project' (which reads) and 'render_preview' (which renders), establishing a unique write operation.

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

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

The description provides explicit usage guidance, including when to use it (e.g., 'After creating project, use render_preview to verify text doesn't block subjects') and alternatives (e.g., 'Use generate_hook_options tool to get 5 high-quality hook variants before writing'). It also specifies prerequisites like following styling rules and hook formulas.

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