DaVinci Resolve MCP Server
Server Quality Checklist
Latest release: v0.2.0
- Disambiguation4/5
Most tools have clearly distinct purposes, and the domain prefixes (project_, media_pool_, timeline_, etc.) help separate workflows. A few potential overlaps exist, such as storage_import_to_pool vs media_pool_import_media, and the many item_* getters could be confusing, but descriptions provide enough detail.
Naming Consistency5/5Tool names consistently follow a domain_verb_noun pattern (e.g., project_create, media_pool_get_clips, color_set_lut), making the set highly predictable. Minor synonyms like 'remove' vs 'delete' are isolated within domains and do not disrupt the overall pattern.
Tool Count2/5212 tools far exceeds the threshold where a toolset becomes overwhelming and hard to navigate. While DaVinci Resolve is a complex application, this many tools is excessive for an agent to effectively choose from, especially with many micro-operations like extension_write_dctl vs extension_write_fuse.
Completeness4/5The toolset covers the major Resolve workspaces (media, edit, color, fusion, fairlight, deliver) and includes practical utilities like ffmpeg probes and CDL/DRX handling. However, fine-grained editing operations (e.g., insert/overwrite edits, trims, transitions) are not exposed, leaving some gaps for full editing automation.
Average 3.8/5 across 192 of 212 tools scored. Lowest: 2.7/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 1 commit in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add
glama.jsonto the root of your repository:{ "$schema": "https://glama.ai/mcp/schemas/server.json", "maintainers": [ "your-github-username" ] }Then . Browse examples.
Add related servers to improve discoverability.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the burden of behavioral disclosure. It only states the action without explaining side effects, whether settings persist, what happens to existing render jobs, or what is returned. This is a significant gap for a setter-type tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence that is immediately clear and waste-free. It is front-loaded with the verb and object, but the extreme brevity leaves out important context that would earn additional sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of a nested settings object with many possible keys and a complex render context, the description is far too minimal. It lacks any information about return values (though an output schema exists), behavioral effects, or how the settings dictionary content maps to render outcomes. The tool likely requires more explanation for reliable use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% because the 'settings' parameter description lists valid keys and indicates additionalProperties. The tool description adds little beyond restating that it's a dictionary, but the high schema coverage means the description doesn't need to compensate. It provides a baseline-3 contribution.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (apply) and resource (render settings), and the phrase 'from a dictionary' indicates the input format. It distinguishes from siblings like render_set_format_and_codec by focusing on a general settings dict, though the boundary with render_load_preset is not explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as render_load_preset or render_set_format_and_codec. There is no mention of prerequisites, context, or exclusions, leaving the agent without enough information to decide correct usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations available, the description carries the full burden of disclosing behavioral traits, but it merely restates the mutation implied by the name. It does not mention whether the property key is validated, whether existing property values are overwritten, whether changes are persisted, or whether special keys like 'Clip Name' have additional effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, front-loaded, and free of filler, which is structurally efficient. However, it barely adds information beyond the tool name itself, so it does not fully earn its place; it is concise but under-specifying.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the parameters and the existence of an output schema, the description need not explain return values, but it should clarify the allowed property keys, the semantics of setting properties, and the difference from sibling tools. The description lacks these contextual details, leaving the agent with insufficient information to confidently select and invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for all three parameters (clip_name, key, value), achieving 100% schema_description_coverage. The description adds only the qualifier 'single property,' which adds little semantic value beyond the schema. A baseline score of 3 is appropriate because the schema handles the parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Set a single property on a clip' clearly identifies the verb (set) and the resource (a clip), so the core purpose is apparent. However, it does not differentiate from the closely related sibling tools clip_set_name, clip_set_metadata, and item_set_property, leaving ambiguity about when this specific tool is the right choice.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives like clip_set_name, clip_set_metadata, or item_set_property. The description only states what the tool does, not when it should be used or what prerequisites or side effects might apply.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It indicates a state-changing action ('switch') but does not explain side effects, whether the item must be selected, permissions required, or what the return value represents. This is a significant gap 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no filler or repetition. It is concise and front-loaded with the key action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, no annotations, and a mutation-like action, the description is underspecified. It omits use cases, prerequisites, behavioral effects, and any guidance on how the parameters relate to the action. The presence of an output schema reduces the need to describe return values, but the description still lacks broader context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and each parameter has a description, so the schema already handles parameter semantics. The tool description adds only the context that this operates on 'grade versions' and 'timeline items', which is minimal extra value. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Switch to a specific grade version') on a clear resource ('a timeline item'). It is more specific than a tautology, but it does not distinguish this tool from the sibling 'color_load_version', which may perform a similar operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'color_load_version', 'color_get_current_version', or 'color_add_version'. There are no prerequisites, context, or exclusion criteria mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only states the action without explaining side effects, prerequisites, track type compatibility (audio vs video), or behavior when the property does not exist. This is a minimal, opaque description 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundancy. It communicates the core action immediately and efficiently, making it concise and appropriately sized for a simple setter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema and a well-documented input schema, the description omits critical context: when to use this generic setter vs. dedicated item_set_* tools, acceptable property keys, and audio/video track handling beyond default. This leaves the agent potentially selecting the wrong tool or misusing it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters with explicit descriptions for key, value, item_name, track_type, and track_index. The description adds no extra semantic value beyond the schema, but since schema coverage is complete, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Set') and the target resource ('a single property on a timeline item'), which is specific and understandable. However, it does not explicitly differentiate itself from sibling setters like item_set_transform or item_set_color, though the generic 'property' wording implies broader applicability.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as item_set_transform or item_set_crop. The description does not state whether this is for arbitrary properties, fallback for uncovered properties, or how it compares to dedicated setters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It only states the action 'Apply smart reframe' without disclosing side effects (e.g., permanent modification, reversibility, what the output indicates). This is insufficient 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the verb 'Apply'. It is efficient, though its brevity leaves out essential behavioral context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 5 parameters and an output schema, the description is extremely brief. It does not explain what smart reframe does, what the result looks like, or any preconditions. This is inadequate for an agent to understand the tool's full behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all parameters are already described in the schema. The description adds no extra meaning beyond the target being a 'timeline item'. The baseline of 3 is appropriate as the description does not contradict or enhance the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'apply' and identifies the resource as 'smart reframe' on a 'timeline item', which distinguishes it from all sibling item_* tools. However, it does not explain what smart reframe actually does (e.g., target ratio, motion estimation), so it is not fully informative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like item_set_transform or item_set_crop. The description provides no context about the use case, prerequisites, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states 'Navigate into a sub-folder', which implies a state change but does not specify error behavior, return value (despite an output schema existing), or whether it operates relative to the current folder.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words. It is front-loaded and easy to parse, earning a top score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple but the description is too minimal: it does not clarify whether 'sub-folder' is relative to the current project folder, what the output schema contains, or how it differs from other navigation tools. Given the large sibling tool set, more context is needed for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully describes the only parameter, folder_name, with 'Name of the folder to open.' The description adds no additional meaning, such as whether the name must be an immediate child or can include a path. With 100% schema coverage, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Navigate into' and a clear resource 'sub-folder within the project database', indicating a folder traversal action. It distinguishes from sibling navigation tools like project_folder_goto_parent/root by specifying 'sub-folder', but does not explicitly contrast with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives such as project_folder_goto_parent or project_folder_goto_root. There is no mention of prerequisites like folder existence or whether the folder is relative to the current project folder.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of explaining behavior. 'Write' implies mutation, but there is no disclosure about overwriting existing values, whether a project must be open, or any error conditions. This is minimal and incomplete 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, brief sentence with no filler or redundant information. It is front-loaded with the action and resource, though it could benefit from a bit more context without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter setter with an output schema present, the description is minimally adequate. However, it lacks usage context and behavioral nuances, making it complete only at a basic level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters with descriptions and examples for 'key' and 'value', so the description adds no parameter-level meaning. The baseline of 3 applies because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Write a project setting,' which specifies the verb and resource clearly. It distinguishes this from sibling tools like timeline_set_setting or project_get_setting by naming 'project' as the target resource, though it doesn't elaborate on what settings are available.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as project_get_setting or timeline_set_setting. The description only states what it does, not under what circumstances it should be chosen.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must fully disclose behavioral traits, but it only states that the tool writes a setting. It does not mention whether the current timeline is required, whether the operation is reversible, what validation occurs, or what success/error behavior to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It is appropriately brief for a simple tool, though it leans toward under-specification rather than elegant conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having a simple schema and an output schema, the description lacks essential contextual guidance for a mutation tool: it does not explain when the setting is applied, whether a timeline must be loaded, or how the tool relates to timeline_get_setting. This leaves the agent uncertain about invocation expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with clear explanations for both 'key' and 'value' parameters, including concrete key examples. The description itself adds minimal semantic value beyond the schema, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the action ('Write') and resource ('timeline-specific setting'), making it clear this is a mutation tool for timeline settings. It distinguishes itself from siblings like timeline_get_setting and project_set_setting by specifying 'timeline-specific', though it doesn't name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool versus alternatives, such as project_set_setting or timeline_get_setting. The phrase 'timeline-specific' implies scope but does not explain prerequisites, side effects, or situations where another tool would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits but only states the action. It does not mention side effects, permissions, impact on references, or any limitations. For a mutation tool, this lack of transparency is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no filler, concisely stating the action. It could include additional usage context, but it remains efficient and front-loaded. The sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and the input schema fully documents parameters, plus an output schema exists. However, the description lacks any guidance about when to rename clips or what consequences result. It is minimally viable but could benefit from additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with both parameters clearly described ('Current name of the clip', 'Desired new display name'). The description adds no extra parameter context, but the schema already provides sufficient meaning, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb (Rename) and resource (media-pool clip), which clearly identifies the action and distinguishes it from sibling tools like clip_get_name or clip_set_metadata. It 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 Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool vs. alternatives, such as what conditions justify renaming or whether clip_set_metadata might be more appropriate for other edits. There are no exclusions or context cues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral detail by stating 'Returns True if a file was removed', which is useful. However, it does not disclose potential irreversible effects, error behavior when the script doesn't exist, or required permissions. With no annotations, the description carries the burden but only partially addresses it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with two short sentences. It front-loads the core action and adds a relevant return-value note. There is no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the tool is simple, the description omits essential context about parameter semantics and usage. The return value is mentioned, and the output schema may cover returns, but the lack of parameter guidance and any mention of related tools (like extension_list_scripts) makes it incomplete in context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not explain the 'name' or 'category' parameters. The agent is left to guess what values are valid or what 'category' means, despite it having a default of 'Utility'. This is a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Delete' and resource 'installed script', clearly distinguishing it from sibling tools like extension_remove_fuse and extension_remove_dctl. It unambiguously states what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives, nor are prerequisites or exclusions mentioned. The action is obvious from the name, but the description does not provide context such as 'use to uninstall a script previously written with extension_write_script'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosing side effects and operational details. It merely says 'import' without explaining whether this replaces an existing Fusion comp, modifies an item in place, requires a specific track type, or what happens on failure. This is a significant transparency gap for a mutating operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler words. It efficiently conveys the core operation, though it could perhaps add a bit more context without harming conciseness. Overall, it earns a strong score for brevity and structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema and complete parameter descriptions, the description fails to provide critical contextual information such as how the imported composition integrates with the timeline item, whether existing Fusion effects are overwritten, or if any state prerequisites exist. For a mutation tool, this lack of context leaves the agent uncertain about consequences.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides complete descriptions for all four parameters, so the description adds no additional parameter context. Per the rubric, a baseline of 3 is appropriate when schema coverage is high, and there is no obvious ambiguity in parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Import'), the resource (a Fusion composition .comp file), and the target (a timeline item). It distinguishes itself from sibling fusion tools like fusion_add_comp (creating a new comp) or fusion_export_comp (exporting), 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 Guidelines2/5Does 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, such as fusion_insert_generator or fusion_import_comp's relationship to timeline items. The description implies usage but does not mention prerequisites, exclusions, or preferred alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does not disclose whether the operation mutates the timeline, what happens if the take index is out of range, or any side effects. For a tool that likely changes state, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no redundant phrasing. It is appropriately sized for the tool's simplicity and communicates the core action effectively.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal, and while the output schema exists, the description doesn't explain the effect beyond 'select'. It lacks behavioral context like whether it's reversible or requires multiple takes, leaving some incompleteness for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All four parameters have descriptions in the schema (100% coverage), so the description adds no additional parameter meaning. The baseline of 3 applies because the schema fully documents parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it selects a specific take on a timeline item, using a specific verb and resource. It distinguishes from siblings like item_get_take_by_index by the verb 'select' vs 'get', though it doesn't explicitly clarify that this sets the active take.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor any prerequisites such as needing multiple takes or handling invalid indices. The description only states what it does, offering no context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral details. 'Set the render format and codec' only conveys a mutation; it does not state whether the change persists, affects current render jobs, requires a preset, or what errors occur for invalid combinations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single short sentence that is front-loaded and free of filler. It is concise, though it borders on under-specification; the schema carries the parameter detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite complete parameter schema, the tool description lacks usage context and behavioral disclosure. For a state-changing operation with no annotations, more information (e.g., relationship to render presets, invalid input handling) is needed for an agent to invoke it safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both format_name and codec_name documented including an example and cross-reference to valid-combination getters. The description adds no additional parameter meaning, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Set' and names a precise resource ('render format and codec'), clearly identifying the tool's function. It distinguishes itself from sibling getters like render_get_format_and_codec and the broader render_set_settings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 such as render_set_settings or how to discover valid format/codec combinations. The schema's codec_name description mentions render_get_formats() and render_get_codecs(), but that guidance lives in the parameter schema, not in the tool description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full behavioral disclosure burden. It only states the high-level operation without mentioning side effects (e.g., copy vs. move), prerequisites (e.g., an open project), or potential errors. This is minimal transparency for a mutating operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that leads with the verb and includes only necessary information. There is no redundant phrasing or filler, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter and an output schema, so baseline completeness is acceptable. However, the lack of annotations and absence of usage context (e.g., relationship to media_pool_import_media, whether a project must be open) leaves gaps that could cause incorrect tool selection or invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents the single file_paths parameter with examples. The description adds no extra parameter semantics, so it neither helps nor harms beyond the schema, meriting the baseline score for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Import'), source ('files from media storage'), and destination ('current project's media pool'). It is specific and likely distinct from storage browsing tools, though it does not explicitly differentiate from the sibling media_pool_import_media.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as media_pool_import_media or storage_get_files. The usage is only implied by the wording, with no explicit when/when-not conditions or prerequisite mentions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, but it only states 'Add a flag'. It does not disclose whether existing flags are preserved, whether adding the same color overwrites, what side effects occur, or what is returned. The mutation implication is present but shallow.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word earns its place: verb, object, resource, and qualifier. It is appropriately sized for a tool of this simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter tool with complete schema coverage and an output schema present, the description covers the core purpose. It lacks behavioral nuances, but the simplicity of the operation and the schema's completeness make it mostly adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 little beyond the schema—it restates that a clip and a color are involved, while the schema already describes clip_name and color with examples. No additional parameter meaning is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Add a flag') on a specific resource ('a clip') with a qualifier ('of the given color'). It distinguishes from sibling tools like clip_get_flags and clip_clear_flags by verb and resource, though it doesn't explicitly contrast with item_add_flag or explain the concept of a flag.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as clip_set_color, item_add_flag, or clip_clear_flags. No prerequisites or exclusions are mentioned, leaving the agent to infer usage from the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It does not mention side effects such as whether an existing group membership is overwritten, whether the group must already exist, or which timeline is targeted (implied to be the current one). The word 'assign' implies mutation, but no details are given.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with zero waste. It efficiently communicates the core purpose without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the schema documents parameters and an output schema exists, the tool is a mutating operation with no annotations. Missing context includes which timeline is affected (current timeline is implied but not stated), whether the group must exist, and the exact behavior on reassignment. The description is too sparse for an operation with side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with clear descriptions for all four parameters (group_id, item_name, track_type, track_index). The description adds no additional parameter meaning beyond the schema, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Assign a timeline item to a color group' clearly states the action (assign), the object (timeline item), and the target (color group). It distinguishes itself from sibling tools like color_create_group (creation) and color_remove_from_group (removal).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool, prerequisites (e.g., the color group must exist and its ID obtained via color_get_group_list), or how it differs from alternatives like item_set_color. The description only states the action with no contextual hints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of disclosure. It mentions the boolean return value but does not state that the deletion is permanent, what happens if the file does not exist, or whether related files are also removed. This is a significant gap for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It efficiently conveys the core action and return value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter and an output schema, but the description leaves the 'name' parameter ambiguous and lacks usage guidance. It is minimally adequate but has clear gaps in parameter semantics and behavioral detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'name' has zero schema description coverage, and the tool description does not clarify whether it expects a full path, base name, or file extension. The phrase 'Fuse file' gives minimal context but is insufficient for correct parameter formatting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and the resource ('installed Fuse file'), which distinguishes it from sibling tools like extension_remove_dctl and extension_remove_script. The verb and object 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.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives or prerequisites. It does not mention that this is for removing Fuse files specifically from extension directories, nor does it exclude cases like script or DCTL removal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits on its own. It only states the destination folder, omitting critical details such as the write operation's overwrite behavior (defaulting to true per the schema), potential refusal when overwrite is false, and any side effects on the Scripts menu. This is a sparse disclosure for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the core action and destination. There is no unnecessary repetition or padding. It is appropriately terse for the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the presence of an output schema, the description is missing important context about the installation process, such as the default overwrite behavior, the handling of filename extensions, and the category's effect on menu placement. For a tool that writes files, the description should at least hint at these behaviors, but it doesn't. It is a minimal one-liner that leaves the user guessing about side effects and expected outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 context beyond the schema; it neither clarifies the filename extension logic nor the category parameter's impact. However, because the schema fully documents each parameter, the description doesn't need to compensate, and it doesn't add any misleading information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's function: installing a Fusion/Resolve script into a page-specific Scripts subfolder. It distinguishes from sibling tools that handle DCTLs or Fuses by using the term 'script' and specifying the install location. The verb 'Install' is specific to this operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit context for when to use this tool versus alternatives like extension_write_dctl or extension_write_fuse. It neither states prerequisites nor mentions when not to use it. The only implicit hint is the term 'script' in the description, which is not enough to guide selection among the many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description simply states the action without disclosing error behavior (e.g., what happens if no marker exists at the given frame), whether the deletion is permanent, or any effects on associated data. With no annotations, this minimal disclosure 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clearly worded sentence that directly states the tool's action. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is incomplete for a destructive operation; it does not address edge cases, preconditions, or effects on the timeline. The presence of an output schema does not compensate for missing behavioral context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides full documentation for the single parameter frame_id with its description. The tool description adds little beyond what the schema already states, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Delete'), identifies the resource ('a marker'), and specifies the scope ('on the current timeline'). This clearly distinguishes it from sibling tools like clip_delete_marker and item_delete_marker, 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 Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives such as clip_delete_marker or item_delete_marker. There are no prerequisites mentioned (e.g., needing an active timeline) nor exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states 'Lock or unlock a track' without explaining the meaning of locking (e.g., preventing edits), whether it is reversible, or any permission or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that communicates the core purpose without any redundancy or filler. It is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having a detailed schema and output schema, the description is minimal and lacks usage context and behavioral detail. For a mutating operation with no annotations, this is a significant gap; the agent is left without knowledge of when to use this tool or how locking affects the track.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides complete descriptions for all three parameters (track_type, track_index, locked), so the baseline is 3. The description adds no additional parameter semantics beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (lock/unlock), the resource (track), and the context (current timeline). It distinguishes itself from sibling tools like timeline_set_track_name and timeline_set_track_enabled by focusing specifically on the locked state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 instead of alternatives, nor does it mention any prerequisites or consequences. It simply states what it does, leaving the agent to infer appropriate usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavioral traits. It does clearly state that the operation deletes a marker, which signals destructiveness, but it provides no additional context about error conditions (e.g., if no marker exists at that frame), reversibility, permissions, or potential ambiguity with multiple markers on the same frame. The description largely restates what the name implies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that communicates the essential information without any filler. It is appropriately sized for the tool's simplicity and includes no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation, the description plus schema covers the basic invocation. However, it lacks guidance on when to use this tool vs. the similar delete-marker tools for timelines or items, and it doesn't mention potential edge cases (e.g., missing marker or multiple markers on a frame). The presence of an output schema reduces the need to explain return values, but the missing usage context keeps it from being fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both clip_name and frame_id have meaningful descriptions in the schema. The description adds the phrase 'specific frame' which aligns with frame_id, but no extra semantic value beyond the schema. Per the baseline for high schema coverage, a score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (delete) and the target (marker on a clip), with a specific qualifier (at a specific frame). This directly distinguishes it from sibling tools like timeline_delete_marker or item_delete_marker, and makes the tool's primary 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 Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives. While the name 'clip_delete_marker' and the phrase 'on a clip' hint at the clip context, there is no explicit mention of using this for media pool clips vs. timeline markers or item markers, nor any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
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 transparency. It does not disclose side effects, whether an existing proxy is replaced, permissions required, or the nature of the return value. The description only states the action without any behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. It effectively communicates the core function without extraneous detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, 100% schema parameter coverage, and the existence of an output schema, the description is adequate but minimal. However, it lacks any supplementary context about behavioral edge cases, such as whether an existing proxy is overwritten or if the path must exist. This leaves some gaps for a complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptive parameter definitions. The description adds minimal meaning beyond what is already in the schema—it merely reinforces that the proxy is 'external,' while the schema already specifies 'Absolute file-system path.' Therefore, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Link') and clearly identifies the resource ('external proxy media file to a clip'). It distinguishes itself from sibling tools like clip_unlink_proxy and media_pool_relink_clips by focusing specifically on linking an external proxy.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives, such as clip_unlink_proxy or media_pool_relink_clips. There is no mention of prerequisites, conditions, or scenarios where this tool is preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description gives no additional behavioral context beyond the action itself. It does not mention side effects, prerequisites, or reversibility, which is a significant gap 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that captures the core function. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with two well-documented parameters and an output schema, but the description lacks usage guidance and behavioral transparency. It is minimally sufficient but leaves gaps for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds no parameter semantics beyond what the schema already provides, but it does not need to since the schema fully documents both parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sets the label color on a clip, using a specific verb ('set') and resource ('clip'). It distinguishes from siblings like clip_clear_color and clip_get_color.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 such as clip_clear_color or item_set_color. It only states the action without contextual or exclusionary information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'apply' without clarifying whether the grade is destructive, whether it creates a new version, or if it operates on the current timeline. This lack of side-effect information is a significant gap 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It efficiently states the action, resource, and target, making it highly concise and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the availability of a complete schema and an output schema, the description is minimally viable but leaves gaps: it does not mention the timeline context, potential destructive effects, or when to use this tool against alternatives. These gaps could lead to improper invocation without external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with all five parameters documented, so the baseline is 3. The description adds minimal semantic value by relating 'one or more items' to item_names but does not explain grade_mode values or track defaults beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'apply' with a clear resource 'DaVinci Resolve grade preset (.drx)' and target 'one or more items', which effectively communicates the core function. It distinguishes this tool from sibling tools like color_set_lut or gallery_apply_grade_from_still by focusing on .drx preset application.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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, nor does it mention prerequisites or related tools like drx_inspect for validation. With no context beyond a single sentence, an agent must guess the appropriate invocation scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must disclose behavior on its own. It does not mention side effects (e.g., file creation/overwriting), permission needs, or any preconditions beyond the schema. This is a minimal statement of action with no transparency beyond the verb.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It efficiently communicates the core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high schema coverage and presence of an output schema, the core invocation is understandable. However, the lack of usage guidelines and behavioral context leaves gaps about when to use it and what side effects to expect, so completeness is only adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All five parameters are documented in the schema with descriptions, so the baseline is 3. The description does not add parameter-level detail, but it does contextualize 'combined grade' as the data being exported. The schema still carries the burden for parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Export') and a specific resource ('combined grade of a timeline item') with an explicit output format ('LUT file'). It reads distinctly from sibling color tools like color_get_lut/color_set_lut, which focus on reading/setting LUTs rather than exporting a file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to choose this tool over similar color tools, nor does it mention prerequisites or alternatives. It simply states the action, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavior. It only states 'rename,' which implies a mutation, but offers no details about failure modes, effect on current version, or whether renaming is reversible. No additional behavioral context is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that directly names the action and object. It has no redundant phrasing or rambling, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 6 parameters and an output schema, but the description only covers the basic action. It lacks usage context, such as distinguishing from related version-management operations or explaining the role of track/version options. This makes it minimally viable but incomplete for nuanced selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides thorough descriptions for all 6 parameters, covering 100% of them. The description adds no parameter-level detail, which is acceptable because the schema does the heavy lifting; thus 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb 'Rename' and resource 'grade version on a timeline item,' clearly distinguishing it from sibling tools like color_add_version or color_delete_version. It precisely matches the tool name and removes ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given for when to use this tool versus alternatives such as color_load_version or color_set_current_version. The description does not mention prerequisites, typical workflows, or any exclusions, leaving the agent without contextual selection help.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It states the core action but does not disclose side effects, error behavior on invalid node_index, whether the change applies to a specific color version, or reversibility. Minimal transparency beyond the literal action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with the action, zero redundancy. Perfectly concise for the level of information it provides.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 5 params, 100% schema coverage, and an output schema. The description is minimal but sufficient for basic use. However, it lacks context about how to discover node_index (e.g., via color_get_num_nodes) and does not mention interaction with color versions, leaving some contextual gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 no extra parameter meaning; it does not mention track_type or track_index defaults or clarify node_index orientation (already in schema). Schema fully documents parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb ('Enable or disable') and resource ('specific color correction node'), clearly distinguishing it from sibling tools like color_set_node_label (labeling) and item_set_enabled (item-level enable). The scope is explicit and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, no prerequisites, no exclusions. The description only states what it does, not when or how to prefer it over other node-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
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 only states the action ('rename') with no details on side effects, error conditions, idempotency, or permissions. It does not contradict annotations, but it fails to add behavior context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word is necessary, and it effectively communicates the core action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple rename operation with a fully-described 5-parameter schema and an output schema, the one-line description provides minimal but adequate context. It doesn't explain relationships between parameters or edge cases, but the schema covers parameter meanings. This is a minimum viable description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with clear definitions for item_name, old_name, new_name, track_type, and track_index. The description adds no additional parameter semantics, but the baseline is 3 due to full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Rename'), a resource ('Fusion composition'), and context ('on a timeline item'). This differentiates it from sibling tools like fusion_add_comp, fusion_delete_comp, and fusion_get_comp, which perform other actions on comps.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, such as the timeline item needing an existing Fusion composition, nor any exclusions or references to sibling fusion_* tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavioral traits. It only states the basic action without mentioning side effects, reversibility, permissions, or error conditions. For a mutation tool, this level of transparency is minimal and insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no unnecessary words. It immediately conveys the core purpose and is well-structured for quick scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich schema (100% coverage) and presence of an output schema, the description is adequate in combination with these fields. However, it lacks usage context and behavioral details, leaving some gaps for a 5-parameter tool in a gallery/color domain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are already described in the input schema. The description adds no extra meaning beyond stating the general operation, meeting the baseline but not exceeding it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Apply') and the resource ('color grade from a gallery still') directed at 'timeline items'. It is specific and distinguishable from sibling tools like gallery_get_stills or color_apply_drx, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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, nor any prerequisites or exclusions. It does not mention that still_index comes from gallery_get_stills or any conditions for applying the grade, leaving the agent without context for appropriate invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits, but it only states 'export to disk.' It fails to mention file writing details, potential overwrites, directory creation, or error conditions, leaving significant ambiguity 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It states the verb, object, and destination efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The parameter schema is complete and an output schema exists, but the description omits behavioral context such as file handling, path requirements, or side effects. It is minimally viable but leaves gaps for a tool with no annotation coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover 100% of the parameters, including the default for album_name and the source of still_indices. The description adds no additional semantic meaning beyond what the schema already provides, so a 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Export' with a clear resource ('stills from a Gallery album') and destination ('to disk'), making its purpose unmistakable. It is distinct from sibling tools like gallery_get_stills (retrieval) or gallery_delete_stills (deletion).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs. alternatives. It does not mention prerequisites (e.g., using gallery_get_stills to obtain indices) or when not to use it. The only contextual hint comes from the schema parameter description, not the tool description itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
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 only states the action 'import' but does not disclose behaviors such as whether existing stills are overwritten, how invalid file paths are handled, whether the album is auto-created, or any permissions/errors. This is a significant gap for a tool that modifies gallery state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that directly states the tool's function without any filler or redundancy. It is appropriately sized for the tool's simplicity and front-loads the key action and target.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (2 params, no nested objects) and the presence of an output schema plus full param documentation, the description is minimally adequate. However, it lacks contextual details like whether the album must already exist, supported file formats (though examples are in the schema), and error behavior. This leaves some gaps for a new user.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers 100% of parameters with descriptions for both album_name and file_paths. The description text adds no additional parameter meaning, so it 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.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Import') and resource ('still image files' into 'a Gallery album'), clearly distinguishing it from sibling tools like gallery_grab_still (capture) and gallery_export_stills (export). No ambiguity remains about the core operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. It does not mention that gallery_grab_still is for capturing from the current frame, nor does it state any prerequisites (e.g., album must exist). The only usage hint is embedded in the album_name schema description about defaulting to the current album, which is not in the main description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description must carry the full burden of disclosing side effects. It mentions that it exports to a CSV file, but does not disclose whether an existing file at that path will be overwritten, whether directories are created, or how the 'current folder' is determined if the media pool has multiple folders. This is a significant gap for a tool that writes files.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that immediately communicates the action and target. It contains no redundant information and is easy to parse. The front-loaded verb 'Export' effectively signals the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a simple interface (one parameter) and an output schema exists, so the need for return-value documentation is reduced. However, the description lacks details about which metadata fields are included, whether subfolders are considered, and how errors (e.g., empty folder, invalid path) are handled. It is minimally viable but leaves gaps for a tool operating within a larger media pool context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides a complete description of the single parameter file_path, including an example path and the type (string). The description adds only the phrase 'CSV file', which is already implied by the schema's description. Since schema coverage is 100%, a baseline of 3 is appropriate; no additional parameter context is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Export'), the object ('metadata of all clips in the current folder'), and the output format ('CSV file'). It distinguishes itself from sibling tools like media_pool_get_clips or clip_get_metadata by specifying the batch export to a file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. It does not mention that this is for exporting metadata in bulk to a CSV, nor does it exclude scenarios like needing specific clip metadata individually. The context of 'current folder' is implicit but not framed as a selection criterion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does not disclose whether the import copies or references files, how duplicates are handled, what file types are supported, or any side effects. The phrase 'import media files from disk' is vague about underlying 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word adds meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter and an output schema exists, so return values need not be described. However, the description lacks behavioral details and does not differentiate from storage_import_to_pool, making it only minimally complete for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents file_paths as 'Absolute paths to media files to import.' The tool description adds 'from disk' and 'current Media Pool folder' but does not enrich the parameter semantics further. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('import'), identifies the resource ('media files from disk'), and specifies the destination ('current Media Pool folder'). This clearly distinguishes it from other media pool operations and import tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like storage_import_to_pool. The only contextual clue is 'current Media Pool folder', but there are no explicit exclusions or comparisons to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It only states the action, but does not reveal side effects (changing the current folder for later operations), failure behavior on missing folders, or whether nested paths are accepted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with zero wasted words. It is appropriately sized for a one-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is low-complexity and the parameter schema is complete, but behavioral context is missing. The mention of an output schema lessens the need to explain return values, but the lack of usage guidance and side-effect disclosure leaves gaps for an agent deciding to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter description already states 'Exact name of the target folder.' The tool description adds 'by name,' which reinforces but does not exceed schema meaning. Baseline 3 applies since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Navigate into') and a clear resource ('Media Pool folder') with a mechanism ('by name'). It fully distinguishes this tool from sibling tools like media_pool_get_current_folder, media_pool_create_folder, and media_pool_get_subfolders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool, prerequisites, or alternatives. It does not mention that the folder must exist, that it changes the current folder for subsequent operations, or contrast with similar navigation tools like project_folder_open.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It does not mention whether the file is overwritten, whether a project must be open, or what is returned after success. 'Export' implies file creation but leaves important side effects implicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no redundant information. It effectively communicates the core purpose without wasting words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and the schema is thorough, but the description omits behavioral context such as overwrite behavior, return values, and prerequisites. It also does not clarify how this export differs from sibling archive/save tools, leaving some contextual gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides full parameter descriptions (100% coverage), so the description does not need to repeat them. The tool description adds no additional meaning beyond the schema's already-clear file_path and with_stills_and_luts parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (export), the resource (current project), and the output format (.drp file). This distinguishes it from sibling tools like project_save, project_archive, and timeline_export.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided for when to use this tool versus related tools such as project_archive or project_save. There are no exclusions, prerequisites, or alternative suggestions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
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 fails to mention side effects (e.g., overwriting an existing project, closing the current project, or creating a new project entry). The description only states the basic operation, leaving the agent uninformed about potential destructive or contextual behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence: 'Restore a project from a .dra archive file.' It is concise, front-loaded with the verb, and contains no unnecessary words or redundant details. Every word contributes to the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool, the description is adequate but minimal. It lacks behavioral context such as prerequisites (e.g., must a project be closed?), effects on the current project state, or what happens after restoration. The presence of an output schema partially compensates for return-value omissions, but the description still leaves gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with a single parameter 'file_path' already described as 'Absolute path to the .dra archive file.' The description's mention of '.dra archive file' partially aligns with the schema but adds no new semantic meaning. The baseline of 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Restore'), the resource ('a project'), and the source ('a .dra archive file'). This is specific and distinguishes the tool from siblings like project_open or project_import. The verb+resource construction leaves no ambiguity about the tool's core function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It does not mention that it is the inverse of project_archive, nor does it specify conditions like 'when you have a backup archive' or 'when a project is missing.' The description simply states the action without contextual direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the action without explaining side effects, whether the operation is destructive, or any required project/timeline state. The 'current timeline' phrase provides minimal context but no deeper behavioral insight.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no redundant words. It is appropriately concise and front-loaded with the primary action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, the schema covers all parameters, and an output schema exists, so return format documentation is not needed. However, the lack of usage guidance and behavioral details leaves clear gaps, making this minimally viable but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides complete descriptions for both parameters, including valid track types and the count behavior (repeating API calls). The description adds no parameter-specific meaning, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('add') with a clear resource ('tracks') and scope ('current timeline'), and it accurately conveys that multiple tracks can be added at once. This clearly distinguishes it from sibling tools like timeline_delete_track.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool, what prerequisites exist (e.g., having a current timeline), or any alternatives. It is a bare functional statement with no contextual usage advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full disclosure burden. It only discloses the version/feature requirement, but omits critical behavioral aspects such as whether transcription runs asynchronously, whether the tool returns immediately, what errors occur if the clip is invalid or unsupported, and whether the transcription is stored persistently. This is minimal and leaves significant uncertainty.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences. The first sentence immediately states the action and target; the second adds a necessary prerequisite. There is no fluff or redundant information. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description is short and does not explain the transcription workflow. It does not mention that starting transcription is likely asynchronous or that the transcript can be retrieved later with clip_get_transcript. For an action-oriented tool, this missing contextual guidance makes it incomplete for an agent to know how to use it effectively in a multi-step process.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with clip_name described as 'Name of the clip to transcribe.' The tool description only says 'for a clip' and adds no additional meaning beyond the schema. Since the schema fully documents the parameter, 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action and target: 'Start audio transcription for a clip.' This is a specific verb + resource combination that distinguishes it from siblings like clip_get_transcript (which retrieves) and clip_clear_transcript (which clears). The tool name reinforces the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a prerequisite ('Requires DaVinci Resolve 19+ with speech-to-text support enabled'), which tells the agent when the tool is usable. However, it does not explicitly mention when to prefer this tool over alternatives like media_transcribe or what to do after starting (e.g., use clip_get_transcript to retrieve results). This leaves usage context mostly implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds that the tool returns source code and scopes to installed scripts in a Scripts subfolder, but it does not disclose how the script is located, whether category affects the subfolder, or possible error behavior. No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. 'Return the source' appears first, and the rest of the sentence adds useful scoping to 'installed script in a Scripts subfolder.'
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, omitting return-value details is acceptable. However, the description leaves the category parameter's role unexplained, and given that both parameters are undocumented, the agent may not know how to correctly construct the call. It is adequate for a simple read tool but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has two parameters (name and category) with zero schema description coverage. The description never mentions either parameter, leaving the agent to infer that 'name' identifies the script and that 'category' probably selects a subfolder. This fails to compensate for the complete absence of parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Return the source of an installed script in a Scripts subfolder.' This clearly differentiates it from sibling tools like extension_list_scripts, extension_write_script, and extension_remove_script, which handle listing, writing, and removing scripts respectively.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by indicating it reads an installed script's source from a Scripts subfolder, but it does not explicitly state when to use this tool versus alternatives or provide exclusions. The sibling names offer context, but the description itself lacks direct guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already indicates a safe read operation. The description adds no additional behavioral context such as ordering, pagination, or consequences, but it is consistent with the annotation and does not contradict it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The entire description is one short, front-loaded sentence with no wasted words. It is easily scannable and avoids unnecessary elaboration, perfectly sized for a simple list operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only tool with an output schema and readOnlyHint annotation, the description is adequate but minimal. It relies on the schema to communicate the optional album and current-album fallback, and it omits usage guidance, but the overall context is sufficient for this low-complexity tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully documents album_name (100% coverage), including its default and meaning. The description adds no parameter-specific details beyond this, so the baseline of 3 applies when the schema carries the parameter documentation burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' and identifies the resource as 'stills in a Gallery album.' It distinguishes from siblings like gallery_get_albums and gallery_get_powergrade_stills, though it does not explicitly mention the optional album default behavior, relying on the schema for that nuance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives. It does not mention that this is the read-only listing counterpart to tools like gallery_import_stills or gallery_get_powergrade_stills, nor does it state 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation already declares readOnlyHint=true, so the description does not need to repeat safety. It adds the useful detail that the index is 1-based, which prevents off-by-one errors, but it does not disclose what 'info' is returned, whether an invalid index causes an error, or any other behavioral nuances. This modest addition is consistent with the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that directly states the tool's purpose. It contains no filler, restates the tool name, or repeats obvious information. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity of the operation, the presence of an output schema, and the read-only annotation, the short description is largely sufficient. It could be improved by noting that the item must already have takes or clarifying the return structure, but the output schema likely covers that. The omission of explicit alternatives is a minor gap, but overall the context is adequately complete for this simple getter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage with descriptions for all four parameters, including the 1-based nature of take_index. The description adds no new parameter-level meaning beyond what the schema already conveys, 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.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns information about a specific take identified by a 1-based index, using a specific verb ('Return') and resource ('info about a take'). It is distinguishable from sibling tools like item_get_takes_count (counts takes) and item_select_take_by_index (selects a take), though it does not explicitly differentiate itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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. There is no mention of exclusions, prerequisites, or preferred use cases. A user might infer it is for retrieving take data, but no explicit context or comparison to related item_get_* tools is offered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavioral traits. It does not say whether the analysis modifies the item, how long it takes, whether it is reversible, or what results are produced. The phrase 'stabilization analysis' hints at an action but lacks any details about side effects or output, leaving significant uncertainty.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler words. It states the action and target directly, making it highly concise. While it is minimal, it avoids unnecessary repetition and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema and simple parameters, the description lacks context about the stabilization analysis workflow. It does not explain what the analysis does, whether it is a one-off operation, or how the result is used. For a tool that likely involves a complex feature (stabilization), the description is too sparse to give an agent enough context to confidently invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides complete descriptions for all three parameters (item_name, track_type, track_index), so the baseline is 3 even with no additional parameter details in the description. The description does not add extra meaning beyond the schema, but it also does not need to since the schema is self-explanatory.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Run') and resource ('timeline item') with a clear operation ('stabilization analysis'). It is distinct from sibling item_* tools, which focus on properties, takes, or transformations, so there is no ambiguity about what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used to perform stabilization analysis on a timeline item, but it does not explicitly state when to use it versus alternatives, nor does it mention exclusions or prerequisites. The context is clear enough for a basic agent, but no alternatives or special conditions are noted.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already signals a safe read operation, and the description's 'Return a concise summary' aligns with that. However, the description adds little behavioral context beyond the annotation—no mention of potential costs, file-size implications, or permission requirements. It does not contradict annotations, so a neutral score is warranted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It directly communicates the core action and scope, making it easy to parse and understand.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, read-only, output schema present), the description is largely sufficient. It explains the basic behavior and the output schema presumably details the return structure. A minor gap is the lack of clarity on what 'key streams' specifically includes, but this does not prevent correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the single parameter file_path described as 'Absolute path to a video/audio file.' The description's 'media file' adds no new meaning beyond the schema. Baseline 3 applies since the schema already fully documents the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: returning a concise summary of a media file, specifying 'container + key streams'. This is a specific verb+resource combination that distinguishes it from more general actions, though it doesn't explicitly contrast with sibling tools like media_streams which might also return stream details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as media_streams or media_extract_frame. The description does not mention use cases, prerequisites, or exclusions, leaving the agent to infer when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It does add meaningful transparency by explaining the backend resolution order (faster_whisper then openai-whisper) and the clear error behavior when dependencies are missing. However, it omits other behavioral traits such as output format, model download behavior, or potential latency, so it is only average.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise and well-structured. The first sentence states the core purpose, and the second sentence provides necessary operational detail about fallback behavior and error handling. Every word contributes value, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema and complete parameter descriptions, the description covers the key operational aspects needed for a moderate-complexity tool: the offline requirement, backend fallback ordering, and failure mode. It lacks sibling differentiation and explicit usage context, but it still provides sufficient information for an agent to select and invoke the tool correctly in most situations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with clear descriptions for all three parameters (file_path, model, language). The description does not add any extra meaning beyond what the schema already provides, 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.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: transcribing speech in a media file with Whisper. It identifies the specific action (transcribe) and resource (media file), and the mention of Whisper gives a concrete method. However, it does not distinguish itself from the closely related sibling tool clip_transcribe_audio, so it misses the full differentiation for a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 alternative tools such as clip_transcribe_audio or media_probe. It mentions the offline/optional dependency aspect, which is a usage caveat, but it does not specify when this tool is the appropriate choice or when another sibling should be preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
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 only states 'Switch', which is already implied by the tool name, and does not mention potential failure modes, preconditions, or side effects of changing pages.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently conveys the core action without any redundant or wasteful wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple navigation tool with one fully-described parameter and an output schema, the description plus schema is largely sufficient. It lacks usage context, but core behavior and valid inputs are fully specified, meriting a 4.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the 'page' parameter fully documented and enumerating valid values. The tool description adds nothing beyond the schema for parameter meaning, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Switch') and resource ('Resolve workspace page'), clearly stating the action. Sibling tool playback_get_page contrasts as a getter, so the 'Switch' verb effectively distinguishes this setter tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 or mention alternatives like playback_get_page. There is no context about prerequisites, such as needing an open project, or whether to prefer this over other navigation approaches.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
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 only states the action and a precondition, but does not mention side effects (e.g., whether the original project is modified), whether the archive overwrites existing files, or any error conditions. This is insufficient for a tool that creates a file and may have destructive implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the primary purpose, and the second sentence adds a critical constraint. Every sentence earns its place with no redundancy or wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although an output schema exists and the parameter schema is complete, the description lacks essential context such as when to use this tool versus alternatives, what the archiving process entails, and any caveats beyond the open-project restriction. For a tool that creates an archive file, this minimal description is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage of all parameters with clear descriptions, so the baseline of 3 applies. The description adds no additional parameter information beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the primary action: 'Archive a project to a .dra file.' It names the specific verb (archive), the resource (project), and the output format (.dra), which distinguishes it from siblings like project_save or project_restore_archive.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides one key usage constraint: 'The project must NOT be currently open.' However, it does not explicitly compare with alternatives such as project_export or project_save, nor does it state when this tool should be preferred. The guideline is implied but lacks explicit exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation declares read safety, but the description adds no behavioral context beyond what the annotation provides. It does not disclose whether subfolders are listed recursively or only immediate children, whether hidden folders are included, or any ordering 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is concise and front-loaded, stating the core action and scope with no filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with an output schema and a fully documented parameter, the description is adequate. However, it lacks context about whether the listing is recursive or direct, and it does not differentiate from the similarly named media_pool_get_subfolders, leaving minor ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage for the single volume_path parameter with a clear description and example. The schema carries the heavy lifting, and the description adds no extra parameter semantics, 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List subfolders inside a media storage path' uses a specific verb (list) and resource (subfolders) with clear scoping to media storage. It effectively distinguishes from sibling tools like storage_get_files and media_pool_get_subfolders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives like media_pool_get_subfolders or storage_get_files. It does not mention exclusions, prerequisites, or context, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
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 merging behavior but does not state whether the original items are replaced, whether the operation is reversible, any required permissions, or potential side effects. This is a significant gap 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly two sentences. The first sentence states the action, and the second clarifies the concept. There is no fluff or repetition, and it is front-loaded with the key action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has moderate complexity and no annotations. While the schema fully documents parameters, the description omits important operational context such as whether items need to be contiguous, whether the timeline is destructively modified, and what the output schema returns. The presence of an output schema helps, but behavioral prerequisites and side effects are still unclear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with descriptions, so the baseline is 3. The description does not add extra meaning beyond the schema; it only mentions 'specific track' which aligns with the track_type and track_index parameters but adds no additional semantic detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb and resource: 'Create a compound clip from timeline items on a specific track.' It also adds an explanatory second sentence ('A compound clip merges multiple timeline items into one editable unit') that reinforces the purpose and distinguishes this from other timeline tools like timeline_create_fusion_clip.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you want to merge timeline items into an editable unit, but it does not explicitly state when to use this tool over alternatives or provide exclusion criteria. It gives clear context without naming any alternatives, so it earns a middle score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description repeats the readOnlyHint annotation by saying 'Read' but adds no additional behavioral context, such as behavior for missing keys, return format, or side effects. Since annotations already declare safety, the description offers no extra value beyond the structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It communicates the core purpose efficiently without sacrificing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one parameter, read-only, output schema present), and the description is sufficient given that the input schema details valid keys and the output schema likely describes return values. The description lacks nothing critical for a basic getter, though it could mention current timeline context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage for the only parameter 'key' is 100% with concrete examples provided in the schema description. The phrase 'by key' merely restates the parameter name and adds no additional meaning beyond what the schema already documents, aligning with the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Read') and clearly identifies the resource ('timeline-specific setting') with the key parameter. It differentiates from sibling tools like timeline_set_setting by indicating a read operation, and from project_get_setting by specifying 'timeline-specific'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus alternatives such as timeline_set_setting or project_get_setting. Usage is only implied by the verb 'Read' and the noun 'setting', with no mention of preconditions or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, but it only states the action without disclosing behavior on missing/invalid names, whether activation is idempotent, or how the current project context is affected. The schema's 'Searches all timelines' hint is not in the description itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tight sentence with no filler. It front-loads the action and resource clearly, earning every word.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with an output schema, the description plus detailed schema parameter is largely complete. Minor gaps like error behavior when the name is not found are not covered, but the tool is simple enough that this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and already explains 'name' as an exact timeline name to activate, so the description does not need to add much. The phrase 'by name' aligns with the schema but adds no new semantic depth beyond it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Set'), the resource ('current timeline'), and the method ('by name'). It distinguishes this from sibling tools like timeline_get_current (retrieve) and timeline_set_name (rename).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives such as timeline_get_by_index or timeline_get_current. The description implies the use case (activating a timeline by its exact name) but does not state exclusions or mention sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
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, but it only states the action without mentioning side effects, error conditions, or return behavior. It does not contradict annotations (there are none), but it offers very little beyond the basic operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler or redundancy. Every word earns its place, and it is appropriately minimal for a simple setter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple: one required parameter, an output schema likely present, and a clear operation. The description, while sparse, is sufficient for the agent to understand the core action and parameter. It lacks only minor usage nuance (e.g., what 'current timeline' implies) but is otherwise complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully describes the single required parameter (name) with 100% coverage, so the description adds no extra semantic value beyond restating 'new name'. Baseline 3 applies given the high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Rename') with a clear resource ('the current timeline'), and this unambiguously distinguishes it from sibling tools like timeline_get_name (read) and timeline_set_current (changing the active timeline).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for renaming the current timeline but provides no guidance on preconditions, when to choose this over other rename/set tools, or any exclusions. It does not mention alternatives like timeline_set_track_name, leaving the agent to infer from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden but only discloses the basic action. It does not mention side effects like rendering impact, reversibility, or prerequisites, leaving behavioral traits vague.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words, clearly stating the tool's core function without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple mutation tool with full parameter descriptions and an output schema, the description adequately scopes the operation to the current timeline. It lacks some caveats but is sufficiently complete given the schema and output schema coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are already well-documented. The description adds no parameter-specific semantics beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action (enable/disable) on a track within the current timeline, using a specific verb and resource that distinguishes it from sibling track operations like timeline_set_track_locked or timeline_set_track_name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as timeline_set_track_locked. The description only states what it does without context on preferred use cases or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds minimal context beyond the destructiveHint annotation by clarifying that it removes 'a specific' flag color, not all flags. However, it does not disclose other behavioral details such as whether the operation is reversible or what happens if the flag color is not found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the essential information efficiently. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (2 params, no enums, output schema present), but the description lacks usage guidance and any caveats. Given the destructiveHint annotation, the description does not fully address the operational context, so a mid-range score is warranted.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters (color, clip_name) are described in the schema. The description adds no additional semantic meaning beyond what the parameter descriptions already provide, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Remove a specific flag color from a clip' uses an imperative verb and clearly identifies the resource (clip) and the specific action (removing a flag color). It distinguishes itself from sibling tools like clip_clear_color or clip_add_flag by specifying 'flag color'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention prerequisites (e.g., clip must exist, flag color must be present) or contrast with clip_add_flag or clip_get_flags.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It states the core mutation but does not disclose side effects such as whether the original file is preserved, whether the clip's duration or metadata updates, or what happens if the new file is incompatible. This is a significant gap 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no filler. It is appropriately sized for its scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with a complete schema and an output schema, the description is minimally adequate. However, it lacks behavioral context about the replacement process and potential side effects, making it incomplete for an agent needing to predict outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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. The description adds no additional meaning beyond paraphrasing the action; it does not clarify format, validation, or edge cases.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('replace') and names the resource ('a clip's media file'), clearly distinguishing it from sibling clip operations which manage names, metadata, markers, flags, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case: replacing the media file of a clip. However, it provides no explicit guidance on when to use this tool instead of other clip operations, nor any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral disclosure burden. It only states the action and does not mention whether existing fields are overwritten, whether empty values are allowed, what the output looks like, or any side effects. For a mutation tool, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that immediately states the verb, resource, and scope. Every word contributes value, and there is no filler or repetition of schema information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (3 required params, no nested objects) and has an output schema, so the description need not explain return values. However, it lacks context about when to use it relative to clip_set_property or clip_get_metadata, and does not disclose behavioral details like overwriting existing metadata. It is minimally adequate but not fully complete for an agent to confidently select it among many clip-related tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all parameters (clip_name, key, value) with clear descriptions (e.g., examples for metadata field names). Since schema coverage is 100%, the description adds minimal extra value beyond reinforcing that only a single field is set per call. The baseline of 3 applies because the schema handles the meaning effectively.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Set a single metadata field on a clip' uses a specific verb ('set') and resource ('metadata field on a clip'), making the function clear. It distinguishes from sibling tools like clip_set_name (sets clip name) and clip_set_property (likely a different concept), and from clip_get_metadata (read vs write).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for setting a single metadata field, but does not explicitly state when to use this tool versus alternatives such as clip_set_property or clip_get_metadata. There are no exclusions or alternative recommendations, so usage guidance is only implied, not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description carries the full burden. It only states the action without disclosing side effects (e.g., whether the new version becomes active, name uniqueness requirements, or effects on existing versions). The word 'local' adds a small constraint, but this remains a thin mutation description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence communicates the operation in 11 words. No filler or duplication of schema details; it earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a relatively simple create operation, the combination of complete schema descriptions and an output schema makes the minimal description workable. However, it omits usage context (current timeline, version management workflow) that would help an agent choose correctly among the many color_version sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and all four parameters (item_name, track_type, track_index, version_name) have meaningful schema descriptions. The tool description itself adds no parameter-specific meaning, but the schema fully compensates, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Create') and identifies the exact resource ('new local grade version on a timeline item'). It clearly distinguishes from sibling version tools such as color_load_version or color_delete_version by specifying it creates a new local version on an item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when/when-not or alternatives are given. The phrase 'on a timeline item' implies it is for adding a version to an existing item, and sibling tools define the surrounding version workflow, but the description does not state when to prefer this over color_load_version or color_get_versions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The destructiveHint annotation already signals the destructive nature, and the description does not contradict it. However, it adds little beyond the annotation—no mention of irreversibility, remote vs local version implications, or side effects, so behavioral transparency is only minimally adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single focused sentence with no filler. It is front-loaded with the core action and resource, making it highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal but supported by a full parameter schema, a destructiveHint annotation, and an output schema. It lacks contextual guidance such as how to list available versions before deletion or what happens on failure, so it is adequate but not rich.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 meaning beyond the schema, but the parameter descriptions in the schema already explain item_name, version_name, track_type, track_index, and version_type adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb (Delete) with a clear resource (grade version) and location (timeline item). This distinguishes it from siblings like color_rename_version, color_load_version, and color_delete_group.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor are prerequisites (e.g., version must exist) mentioned. The description only states the action without usage context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only restates the core action without mentioning edge cases, failure conditions, prerequisites, permissions, or side effects. For a mutation tool, this is insufficient transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence, front-loaded with the action, and contains no redundant information. It is appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple removal tool, the core operation is clearly stated. However, it lacks behavioral detail and usage guidance. With an output schema present, return formatting is covered externally, but overall completeness is acceptable yet not outstanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 4 parameters with descriptions, so baseline 3 applies. The description adds no additional parameter semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Remove' and specifies resource 'timeline item from a color group', clearly distinguishing it from sibling tools like color_assign_to_group and color_create_group.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for removing items from groups but provides no explicit context, alternatives, or exclusions. Since there are no annotations or additional guidance, it relies on the tool name to convey when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for disclosing behavior. It only states the action without mentioning side effects such as overwriting existing LUTs, requiring an existing node, or behavior on invalid LUT paths. This is a significant gap 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the verb and resource. Every word earns its place, and it is appropriately minimal for a tool with rich schema coverage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a 5-parameter schema and no annotations, the description is adequate for identifying the operation but lacks behavioral context (e.g., whether it replaces the existing LUT) and prerequisite information. The schema covers parameters, and an output schema exists, but the description still leaves some gaps in operational understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all parameters, so the baseline is 3. The description adds no extra meaning beyond the schema—it mentions a 'LUT file' and 'specific node' but doesn't elaborate on path format, node indexing, or track selection beyond what schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'apply' with a clear resource (LUT file) and target (node on a timeline item), distinguishing it from siblings like color_get_lut (read) and color_export_lut (export). It is unambiguous about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the usage scenario (applying a LUT to a node) but does not explicitly mention alternatives or when not to use it. Siblings like color_get_lut exist for reading, but the description doesn't reference them, leaving exclusion guidance implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full behavioral disclosure burden. It implies mutation via 'Set' but does not disclose whether existing labels are overwritten, the consequences of an invalid node_index, or any side effects on color versions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one sentence with no filler, front-loading the action verb and object. It is appropriately sized and every word contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema fully documents all parameters and an output schema exists, so return values need not be explained. However, the description itself is minimal and lacks context about prerequisites or side effects, leaving some ambiguity for a mutation tool without annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides complete descriptions for all five parameters (100% coverage), so the description adds no additional parameter semantics. Baseline 3 applies because the schema already handles parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Set' and identifies the resource ('label on a specific color correction node'), which clearly distinguishes it from sibling tools like color_get_node_label and color_set_node_enabled. It is concise and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage—to set a node label—but does not explicitly state when to use it over alternatives or mention prerequisites. It also doesn't reference related tools such as color_get_node_label for reading labels.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states the action without disclosing side effects (e.g., overwriting existing effects), permissions, reversibility, or the potential global application caveat mentioned in the track_index schema description. This is a minimal disclosure for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that efficiently conveys the core purpose. No wasted words or redundant elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple apply operation, but the description and schema omit prerequisites (e.g., existing audio track, timeline state) and potential caveats beyond the note about global application in the schema. With an output schema present, return values may be covered, but overall context is adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters well-documented (exact preset name, 1-based track index). The tool description adds no additional parameter context, but the schema already provides strong semantics, so a baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Apply a Fairlight audio effect preset to an audio track' uses a specific verb and resource, clearly stating the tool's function. It is unambiguous and distinguishes itself from sibling tools like fairlight_get_presets or fairlight_insert_audio.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the action: apply a preset to a track. The schema description for preset_name references fairlight_get_presets, suggesting a prerequisite workflow, but there is no explicit when-to-use or alternatives mention.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It does not mention side effects, prerequisites, or whether the operation modifies the project file. The statement is a bare action without additional context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the essential purpose without unnecessary words. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a simple operation, with full schema coverage and an output schema present. However, it lacks usage context and behavioral details that would make it more complete for an agent unfamiliar with the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents all three parameters with descriptions, so the description does not need to add parameter semantics. It receives the baseline 3 because the schema coverage is 100% and the description adds no further parameter detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (add), the object (color correction node), and the target (timeline item's node graph). It distinguishes this tool from sibling color tools such as color_set_lut or color_set_node_enabled by specifying the node-graph addition context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternative guidance is provided. The usage is only implied by the description text, which meets the minimum threshold for implied usage but does not go further.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
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 only states the action without disclosing potential side effects, error conditions, prerequisites, or whether it mutates the item's color. For a mutation tool, this is a significant transparency gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the action and target. No wasted words; it is concise and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple setter with a well-documented schema and an output schema present, the description is adequate but not complete. It lacks explicit usage guidance and behavioral transparency, which are important for an agent to select and invoke it correctly, especially given sibling tools like item_set_property and clip_set_color.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with clear parameter descriptions. The tool description adds only the context that 'color' refers to a label color, which is marginally useful. Baseline 3 is appropriate because the schema handles parameter semantics well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Set') and resource ('label color on a timeline item'), clearly distinguishing it from sibling tools like clip_set_color (clip vs. timeline item) and item_get_color (get vs. set). The scope is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrasing 'timeline item' implies it is for items on a timeline, subtly differentiating it from clip-level tools, but there is no explicit when-to-use guidance or mention of alternatives. The intended use case is clear enough but not spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only says 'Set composite mode and/or opacity' without disclosing side effects, reversibility, or permissions. It does not mention that this is a mutating operation with potentially persistent effects, nor any constraints on when it works (e.g., only on video tracks).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the action and resource. Every word earns its place, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 5 parameters with full schema coverage, but no annotations and an unknown output schema. The description is adequate for a basic setter tool, yet it lacks behavioral context such as prerequisites (item must exist), range validation beyond schema, or what happens on failure. It is complete enough for simple usage but misses deeper context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%; the schema already documents mode, opacity, item_name, track_type, and track_index. The description adds the 'and/or' semantics (can set one or both) but otherwise provides no additional parameter detail beyond what the schema already includes.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Set), the resource (composite mode and/or opacity), and the target (timeline item). It distinguishes itself from sibling tools like item_set_property or item_set_transform by specifying composite mode and opacity specifically.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the name and description: use this tool to set composite mode or opacity on an item. However, it does not explicitly state when to choose this over alternatives like item_set_property, nor does it mention limitations such as video-only applicability or track type restrictions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, so the description adds limited extra behavioral context: it specifies deletion is by name and targets subfolders. The schema also notes the search scope is 'current folder's children', but the description does not explain potential consequences like recursive deletion or failure 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant words. Every part contributes directly to understanding the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter and an output schema, so the description covers the core functionality. However, for a destructive action, it would benefit from noting whether nested subfolders are deleted recursively or if any safety checks exist. The current level is adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for the only parameter, folder_names, explaining it is a list of names to delete from the current folder's children. The description adds minimal extra meaning beyond 'by name', so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Delete') and resource ('Media Pool subfolders') with a qualifier ('by name'), clearly distinguishing it from sibling tools like media_pool_create_folder or media_pool_delete_clips.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. The description only states what it does, leaving usage context to be inferred from the tool name and schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full burden for behavioral disclosure. It indicates a mutation (move) but does not disclose side effects, reversibility, prerequisites, or error behavior. The schema adds some info about target folder search scope, but the description itself is sparse.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single, focused sentence that communicates the essential action with zero redundancy. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, and the schema covers parameters; output schema exists. However, with no annotations and minimal description, behavioral context (like what happens on failure or whether clips are removed from the source) is incomplete. Adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and parameter descriptions are informative (e.g., target folder searched in current folder's siblings and root children). The description does not add meaning beyond the schema, but the baseline of 3 applies due to full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Move clips from the current folder to a different Media Pool folder,' using a specific verb and resource. It distinguishes itself from siblings like media_pool_delete_clips or media_pool_relink_clips by defining the action of relocating clips between folders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for reorganizing clips in the Media Pool but does not explicitly state when to use it vs alternatives. No exclusions or alternative tool references are provided. The context is clear but not elaborated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only states the action without revealing side effects, prerequisites, failure modes, or whether the relink is reversible. There is no mention of what happens if matches are not found or how it modifies clip state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that clearly states the operation without wasted words. It is front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with an output schema, the description covers the basic purpose, but it lacks guidance on edge cases (e.g., clips that cannot be matched) and does not differentiate from closely related media pool operations. It is adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are fully described in the schema (100% coverage), so the description adds no new semantic detail beyond the schema. The baseline of 3 is appropriate since the schema already documents the parameters adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific verb 'relink' and the resource 'offline clips to media files in a new folder,' which distinguishes it from sibling tools like clip_link_proxy or media_pool_import_media. It precisely conveys the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'offline clips' implies the intended scenario, but the description provides no explicit guidance on when to use this tool versus alternatives, no exclusions, and no mention of related tools. It offers only an implied usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description is the only source of behavioral info. It discloses that the tool returns True if the save succeeded, which implies possible failure, but it does not describe side effects such as overwriting the current saved project or error cases (e.g., no open project). This is moderate transparency but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with two short lines. The return statement is useful and not redundant. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, single-action tool, the description is adequate: it states the action and the return value. However, it lacks context about the save destination (e.g., current database) and any prerequisites, which slightly reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool accepts no parameters, so the description needs no parameter guidance. Baseline 4 for 0 params.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Save the current project') with a specific verb and resource. It differentiates from siblings like project_export/archive by the verb 'save', but does not explicitly mention alternatives, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to save, prerequisites (e.g., project must be open), or how it compares to project_export/archive. It simply states the action, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
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 does not mention side effects, whether rendering runs asynchronously, whether a project must be open, or what happens if no jobs are queued. The description is too sparse to inform the agent about important 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that immediately states the tool's purpose. It is appropriately sized for a simple action and contains no filler or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple with only two optional parameters and an output schema. The description covers the core action but omits prerequisites (e.g., having a project open) and the behavior of the rendering process. It is adequate but leaves meaningful gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for its two parameters, so the schema already fully documents them. The description adds no parameter-specific semantics, but given the high schema coverage, a 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Start rendering queued jobs' uses a specific verb ('start') and resource ('queued jobs'), clearly distinguishing it from sibling tools like render_stop and render_add_job. It unambiguously identifies the tool's action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The imperative phrasing implies usage when the user wants to initiate rendering of queued jobs, but there is no explicit guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. It relies on the tool's name and basic context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It states the mutation ('Add a marker') but does not disclose prerequisites (e.g., an open timeline), whether markers can overwrite existing ones, side effects on the timeline, or what the return value indicates. Minimal behavioral insight beyond the raw action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Exactly one sentence with no fluff. It front-loads the core action and target, and all parameter details are left to the schema, making it appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a straightforward mutation with six fully-documented parameters and an output schema. However, with no annotations and a terse description, it lacks context about the 'current timeline' requirement, differentiation from clip/item marker tools, and any prerequisites. For a tool with moderate complexity and many marker-related siblings, this is minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents all six parameters with descriptions (100% coverage), so the description does not need to repeat them. The phrase 'at a specific frame' aligns with frame_id but adds no additional semantics. Baseline of 3 is appropriate given the schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (add), the resource (marker), the target (current timeline), and the location constraint (at a specific frame). It effectively distinguishes itself from sibling tools like clip_add_marker and item_add_marker by specifying 'current timeline'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage—when a timeline marker is needed at a specific frame—but provides no explicit guidance on when to use this tool versus clip_add_marker or item_add_marker, nor any exclusions. It lacks explicit alternatives or when-not-to-use scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, and the description's 'Delete' is consistent. However, beyond the bare action, the description does not disclose important behavioral traits such as the removal of all clips on the track or consecutive track indices shifting after deletion. This leaves the agent without side-effect awareness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no redundant words. It is front-loaded and immediately states the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with full schema coverage and a destructive annotation, the description is adequate but not comprehensive. It omits side effects like clip deletion and index reordering, which are relevant for a destructive operation. The existence of an output schema somewhat reduces the burden, but the lack of behavior disclosure keeps it at a minimal viable level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes both parameters fully (track_type with allowed values, track_index as 1-based). The description adds no additional meaning beyond what the schema provides, so a baseline score of 3 is appropriate given 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a track from the current timeline' uses a specific verb ('Delete') and resource ('track') while clearly scoping to the 'current timeline'. This distinguishes it from sibling tools such as timeline_delete_clips, which deletes clips rather than tracks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through the verb 'Delete' and mentions the 'current timeline' as context, but it does not provide explicit when-to-use versus alternative guidance or exclusions. No prerequisites like having a current timeline set are stated, and no alternative tools are referenced.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
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 only states that it exports the current timeline, but does not mention side effects like overwriting existing files, permission requirements, or prerequisite that a timeline must be loaded. This leaves significant behavioral ambiguity for an export operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that directly states the tool's purpose. It contains no unnecessary words or repetition, making it appropriately concise and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given 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), rich schema, and presence of an output schema, the description is adequate but not complete. It lacks context about prerequisites (e.g., active timeline), file overwrite behavior, and connection to related timeline tools, leaving gaps that the schema alone cannot fill.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage with descriptive text for all three parameters (file_path, export_type, export_subtype). The description adds no new parameter information beyond the schema's own definitions, so the baseline of 3 applies without compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Export' and the resource 'current timeline' to a file, and lists common formats (AAF, EDL, FCPXML) which distinguishes it from sibling tools like render_* or project_export. It is 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.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when the current timeline needs to be exported to a file, but it does not explicitly state when to use it versus alternatives, nor provide any exclusions. There is no reference to sibling tools like timeline_render or project_export, leaving the 'when' largely implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. It discloses the output format (standard ASC CDL v1.01) but omits critical write behavior such as whether the file is overwritten, created if missing, or any failure/error conditions. This is a significant gap for a file-writing tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences and front-loaded with the primary action and target. Every sentence adds relevant detail (format and import compatibility), with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has only one required parameter, a complete schema, and an output schema exists, so return values need not be explained. The description covers the core purpose and output format. It could be more complete by addressing overwrite behavior, but overall it is sufficient for a simple write operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with all six parameters individually described. The tool description itself does not add parameter-level meaning beyond the schema, 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Write') and resource ('a single ASC CDL correction to a .cdl file'), clearly identifying the tool's function. It also distinguishes from sibling tools like cdl_read and color_set_cdl by specifying the file-based output format.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'that Resolve and other tools can import as a primary grade' implies usage context (export for import elsewhere), but there is no explicit guidance on when to prefer this over alternatives or exclusions. Usage is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation destructiveHint already signals the mutating nature. The description adds that it resets to default, which clarifies the outcome, but offers no further behavioral detail such as reversibility or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence front-loaded with the action, containing no superfluous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter, a destructive annotation, and an output schema, the description sufficiently states the purpose and result. It does not address edge cases, but that is acceptable given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (clip_name is described as 'Name of the clip'), and the description does not add extra meaning beyond that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Remove') and resource ('label color from a clip'), making the tool's function immediately clear. It also distinguishes it from sibling tools like clip_set_color and clip_get_color.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like clip_set_color, and there are no explicit usage conditions or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is consistent with the destructiveHint annotation, and the act of clearing is inherently destructive. However, it adds no additional behavioral context beyond the annotation—it does not clarify whether clearing is irreversible, whether it affects other clip data, or any side effects. With annotations covering the destructive nature, a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence of eight words. It front-loads the action and target without any filler or redundancy, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter, a destructive hint, and an existing output schema, the description adequately captures the core functionality. It lacks explicit usage guidance, but given the tool's simplicity, it is sufficiently complete. A few words about irreversibility or affected data would push it to 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents the sole parameter 'clip_name' with the description 'Name of the clip.' The tool description adds no additional meaning about the parameter, but since schema coverage is 100%, 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Clear') and resource ('transcript text') with a clear target ('from a clip'). It effectively distinguishes from sibling tools like clip_transcribe_audio (which creates transcripts) and clip_get_transcript (which retrieves them), making its purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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. It does not mention when to prefer this over clip_get_transcript or clip_transcribe_audio, nor does it state any prerequisites or side effects. The agent must infer usage entirely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds no further behavioral context (e.g., prerequisites, performance, side effects). It only restates the scope of the read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single, focused sentence that is immediately clear and contains no filler. Front-loaded with the action and key details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and a readOnly annotation, the description is adequate for a simple one-parameter getter. It clearly names the tool's purpose and examples, though it leaves return format details to the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for clip_name ('Name of the clip to inspect'), so the description does not need to add parameter details. It adds no additional semantic nuance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies a verb ('Return') and a resource ('all clip properties'), with concrete examples (Clip Name, Duration, FPS). This distinguishes it from sibling getters like clip_get_name or clip_get_metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is the comprehensive property getter ('all clip properties') but provides no explicit when-to-use vs alternatives, no exclusions, and no mention of sibling tools like clip_get_name or item_get_properties.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already declares the operation as non-destructive, and the description adds useful scoping with 'current node'. It does not disclose error behavior or return format, but that is partly covered by the output schema and the read-only annotation. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single, focused sentence that uses a clear subject-action-object structure. It contains no filler, repetition, or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with a complete input schema and an output schema, the description is sufficient. It clearly identifies the source and scope ('timeline item's current node'), and missing details like node selection semantics are minor given the structured metadata.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage for all three parameters with clear descriptions. The description adds no extra parameter semantics beyond aligning 'timeline item' with item_name, so the baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a read action on ASC CDL values, scoped to a timeline item's current node. It distinguishes from setters like color_set_cdl by using 'Read' and from broader operations like cdl_read_all via the 'current node' qualifier, though it does not explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The verb 'Read' implies usage for retrieving current CDL values, and the scoping to a timeline item's current node provides context. However, there is no explicit when-to-use or comparison with sibling tools, leaving selection to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, and the description is consistent with this, describing a read-only operation that returns a count. However, the description adds no extra behavioral context such as edge cases (e.g., returns 0 if no versions) or dependencies on version_type parameters. Given the annotation covers safety, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short sentence (12 words) that directly states the tool's function without any filler. It is front-loaded and every word earns its place, making it an exemplary concise description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only count tool with a high-coverage schema and an output schema present, the description provides sufficient context: it names the input (timeline item) and output (number of grade versions). It doesn't mention the version_type distinction, but that is already documented in the schema. Minor gap: it could explicitly note that the count respects the version_type parameter, but overall it is 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/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the schema already describes all four parameters (item_name, track_type, track_index, version_type). The description adds no additional parameter-level meaning beyond stating the tool operates on a timeline item, which is already implied by item_name. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Return') and resource ('the number of grade versions on a timeline item'), clearly distinguishing it from related tools like color_get_versions (which lists versions) and color_add_version (which adds versions). The purpose is immediately unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of color_get_versions for detailed version info or any other related tool. The description only states what it does, leaving the agent to infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already signals a safe read operation, so the description does not need to repeat that. It adds the 'installed DCTL file' constraint but does not disclose error behavior, file format, or what 'source' entails. With annotations carrying the safety profile, the description is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant words. It conveys the essential purpose without padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter and an output schema, so the description could be minimal. However, it lacks parameter semantics and usage context, making it only minimally complete for a single-param tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides a single 'name' parameter with no description, and the description does not elaborate on it. While 'name' likely refers to the DCTL file name, this is inferable only from the tool name, not explicit. Given 0% schema coverage, the description should compensate but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Return' and the resource 'source of an installed DCTL file', making it distinct from sibling tools like extension_write_dctl or extension_remove_dctl. The verb-resource pairing is 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.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for reading a DCTL file's source but does not explicitly state when to prefer this over alternatives or mention any prerequisites. The context of 'installed' hints at extension management, but no explicit guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It states 'writing into the Fuses directory' but does not mention overwrite defaults, potential to replace existing files, filesystem side effects, or permissions. The schema describes the overwrite parameter, but the description itself omits this context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It directly states the action and target location, earning a perfect conciseness score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple write operation, 100% parameter schema coverage, and the presence of an output schema, the description is largely complete. It states the purpose and destination. However, it could have mentioned the overwrite default behavior (which is only in the schema) to provide fuller contextual awareness for a file-writing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 minimal parameter meaning beyond the schema, only indirectly referring to 'Lua source' and 'Fuses directory', which aligns with code and name parameters but does not clarify semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Install') and resource ('Fuse by writing its Lua source into the Fuses directory'), clearly distinguishing it from sibling tools like extension_remove_fuse (removal) and extension_write_script (different file type).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (install a Fuse) but does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions or prerequisites. It relies on the tool's name and context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It states the action (export) but does not disclose potential side effects such as overwriting existing files, whether the composition must be open, or any required permissions. This is a significant gap for a file-writing operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with 11 words, front-loaded with the verb and resource. Every word earns its place, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of a full output schema and 100% parameter description coverage, the minimal description is sufficient for basic invocation. It does not explain prerequisites or side effects, but those are not necessary given the schema richness and are more related to behavioral transparency.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all five parameters already have clear descriptions. The tool description adds no additional meaning beyond what the schema provides, which matches the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Export' and a clear resource 'a Fusion composition' with a destination '.comp file on disk'. This clearly distinguishes it from sibling tools like fusion_import_comp or fusion_delete_comp.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for exporting a Fusion composition to a .comp file, but it does not explicitly mention when to use this tool versus alternatives like fusion_import_comp or timeline_export. No exclusions or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already establishes safety, and the description adds only modest scope detail ('all tools', 'specific composition'). It does not disclose additional behaviors such as permissions, edge cases, or whether the operation can fail, but the annotation lowers the bar.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
One front-loaded sentence with no filler. Every word contributes to understanding the purpose, 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.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The rich input schema and readOnlyHint make the one-line description mostly sufficient, but it does not mention that the composition is reached through a timeline item (item_name) or that track_type/track_index locate the clip. The schema fills this gap, so it is a minor omission rather than a structural flaw.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: all parameters have descriptions. The description adds no parameter-level meaning beyond what the schema already provides, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('all Fusion tools inside a specific composition'), clearly distinguishing it from siblings like fusion_get_comp_count and fusion_get_comp_names that operate on compositions themselves.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 vs alternatives, no prerequisites, and no exclusions. It only states the core function, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
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 only says 'Add a flag', which implies mutation, but does not mention side effects such as whether duplicate flags are allowed, color constraints, or any required permissions. This is a significant gap 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise, front-loaded sentence that wastes no words. It clearly communicates the action and target without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the operation, the presence of a full output schema, and complete parameter descriptions, the description is mostly complete. However, it lacks any usage guidance or behavioral details, which prevents a perfect score. The absence of annotation support is partially mitigated by the schema and output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all four parameters with descriptions, including defaults for track_type and track_index. The description adds no extra parameter semantics beyond the schema, so the baseline of 3 applies since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (add a flag), the resource (timeline item), and the color parameter. It distinguishes itself from sibling tools like clip_add_flag by explicitly saying 'timeline item', and from item_get_flags by indicating a write operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage on timeline items, which differentiates it from clip_add_flag, but it does not explicitly state when to use this tool vs alternatives. There is no mention of exclusions or prerequisites, so the guidance is minimal but not misleading.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
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 only states the action without explaining side effects such as whether adding a marker overwrites an existing one, whether markers are appended, or any permissions required. For a mutation tool, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single declarative sentence that front-loads the action and target, with no filler or redundant information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity of a marker-add operation, the presence of an output schema, and 100% parameter schema coverage, the description plus schema is largely complete. The only notable gap is the lack of explicit usage distinction among sibling marker tools, which is already accounted for in the usage guidelines dimension.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline applies. The description adds the contextual 'frame offset' for frame_id, but all other parameters are already fully documented in the schema. The description does not need to elaborate further, so a score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('Add a marker to a timeline item') and explicitly includes the frame offset. It clearly distinguishes this tool from siblings like clip_add_marker and timeline_add_marker by specifying the target as a timeline item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly identifies the target resource ('timeline item') but does not explicitly state when to use this tool over alternatives like clip_add_marker or timeline_add_marker. No exclusions or alternative tool names are mentioned, leaving usage context implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=true already signals that this is a safe read operation. The description consistently describes returning a count, which aligns with the annotation, but it adds no additional behavioral details such as error conditions, return format, or reliance on the current timeline. With annotations covering the safety profile, the description's minimalism is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the core action and resource. There is zero redundant text, and every word contributes to meaning, making it an exemplar of brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only count tool with complete schema descriptions and an output schema present, the description is clear and sufficient. It doesn't mention prerequisites like the current timeline, but the schema and tool name provide enough context. It could be more explicit about how the item is located, but the overall definition is complete for its simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has full 100% description coverage for all three parameters (item_name, track_type, track_index), so the schema already documents their meaning. The tool description does not add extra explanation about parameters, which is acceptable given 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.
Purpose5/5Does 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 number of takes on a timeline item.' This is a specific verb (return) plus resource (takes on a timeline item), and it clearly distinguishes from sibling tools like item_get_take_by_index or item_delete_take_by_index by focusing on counting rather than accessing or modifying takes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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, no prerequisites, and no exclusions. It is a standalone sentence without any contextual hints about when counting takes would be appropriate, despite being one of many item_* tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must convey behavioral context. It only states the create action and location, without mentioning error conditions (e.g., duplicate folder names), permissions, or side effects. This is minimal and leaves the agent to assume standard 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no filler. It front-loads the action and location, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter create operation, the description covers the core action and location, and an output schema exists. However, it omits failure behavior (e.g., what happens if the folder already exists) and does not clarify the relationship to the current database folder navigation state, leaving minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter folder_name is fully documented in the schema with a description, so schema coverage is 100%. The tool description adds no additional meaning beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a folder in the current database folder, using a specific verb and resource. This distinguishes it from sibling tools like project_folder_list and media_pool_create_folder, which target different actions or locations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'current database folder' provides implied context for when the tool is relevant, but there is no explicit guidance on when to use this tool versus alternatives such as media_pool_create_folder. No exclusions or alternative tool references are given, so usage is inferable but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The main description does not disclose that opening a project automatically closes and saves the current project. This important side-effect is only mentioned in the parameter description within the input schema, and since no annotations are present, the description carries the full burden but fails to surface it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, 'Open an existing project by name.', which is front-loaded and contains no unnecessary words. It is maximally concise while conveying the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite minimal description, the tool is simple with only one parameter that is well-documented in the schema, and an output schema exists to clarify return values. The combination of description and schema provides sufficient context for correct invocation, though it lacks explicit guidance on alternative tools or error conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'name' is fully documented in the schema, including the requirement for the exact name and the observable side-effect of closing/saving the current project. The main description adds no additional parameter meaning, so with 100% schema coverage, a 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'open' and targets 'existing project by name', clearly distinguishing it from project_create, project_close, and project_delete. It precisely states the action and resource, leaving no ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by specifying 'existing project', which hints at being an alternative to creation tools, but it does not explicitly state when to use this tool vs alternatives or when not to use it. There are no exclusions or alternative tool names mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already signals this is a safe read operation. The description adds that it returns progress for a specific job, but does not disclose further behavioral details (e.g., return format, status values). This is adequate for a simple read tool with an output schema, but not exceptional.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the core purpose without any unnecessary words or repetition. It is maximally concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (one parameter, readOnly annotation, and an output schema that likely defines the progress fields), the description is sufficient to understand the tool's function. The lack of usage guidance is a minor gap, but overall completeness is strong.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with the single parameter job_id already described as 'The job ID to check.' The description adds no additional meaning beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Return'), the resource ('render progress'), and the scope ('specific job'). It distinguishes itself from sibling tools like render_get_jobs, which lists jobs, by focusing on the progress of a single job.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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. Given the many render_* sibling tools, it would be helpful to mention that this is for checking progress of an individual job while render_get_jobs lists all jobs, but the description does not include such context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
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 only says 'Rename a track' with no mention of side effects, permissions required, behavior on invalid track indexes, or reversibility. For a mutation tool, this lacks necessary behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single focused sentence that immediately conveys the tool's purpose. No wasted words; structure is optimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple rename operation with complete parameter schema and an output schema present, the description is nearly sufficient. However, it omits any note about error conditions or prerequisites (e.g., requiring an open timeline), but given the simplicity, this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters (name, track_type, track_index) are fully documented in the schema. The description adds no extra parameter semantics beyond what the schema already provides, which is the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Rename') and the resource ('a track in the current timeline'), which differentiates it from siblings like timeline_get_track_name, timeline_add_track, and timeline_set_track_enabled. The scope 'current timeline' adds important context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage is implied: use this when you want to rename a track in the current timeline. However, there is no explicit guidance on when not to use it or alternatives, such as using timeline_get_track_name to check the current name first, or timeline_set_track_enabled for toggling track state.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
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 only states the action without disclosing any behavioral traits such as whether markers at the same frame overwrite, required permissions, return values, or error conditions. For a mutation tool, this is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence states the action and target without any filler. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a simple add operation with a comprehensive schema, but it lacks context about operational behavior (e.g., duplicate markers, authorization, or frame referencing) and does not clarify how this tool relates to sibling marker tools beyond the resource type. Given no annotations, more context would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds no additional parameter meaning beyond what the schema provides. The phrase 'at a given frame' only echoes the frame_id parameter description. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Add a marker to a media-pool clip at a given frame.' It clearly distinguishes this from sibling marker tools like timeline_add_marker and item_add_marker by specifying 'media-pool clip.' This is precise and 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates the target context ('media-pool clip'), which differentiates it from timeline/item marker tools. However, it does not explicitly name alternatives or provide when-not-to-use guidance, 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already declares this as a safe read operation. The description adds no further behavioral context, such as behavior when no transcript exists, but it does not contradict the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single concise sentence that is front-loaded and contains no filler. Every word contributes to the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and only one parameter, the tool is simple. However, the description omits the key prerequisite that a transcript must already exist, likely generated via clip_transcribe_audio. This leaves a gap for agents unaware of the workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage for the single parameter clip_name with a clear description. The description adds no additional parameter details, 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (get) and the resource (transcript text) scoped to a clip. This distinguishes it from sibling tools like clip_transcribe_audio (create) and clip_clear_transcript (delete).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (when you need a clip's transcript) but gives no explicit exclusions or alternatives. It does not mention that the clip must already have been transcribed, nor does it point to clip_transcribe_audio as the complementary creation tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safe read nature is known. The description adds no extra behavioral context (e.g., what happens if no current version exists), but does not contradict annotations. A simple getter with limited side effects makes this acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that fully communicates the tool's purpose. It contains no redundant information and is appropriately front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only getter with an output schema and full parameter documentation, the description is sufficient. It states the core function and relies on structured fields for additional details, which is appropriate given the low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters are already documented clearly in the schema. The description adds no additional parameter-level meaning, which is fine given the baseline of 3 for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Return') and clearly identifies the resource ('name of the currently active grade version'), making it distinct from siblings like color_get_versions which lists all versions. It precisely states the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., color_get_versions or color_set_current_version). The description only states what it returns, not the context in which it should be chosen.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is consistent with the readOnlyHint annotation and does not contradict it. However, it adds no behavioral context beyond the annotation, such as error handling, return format, or edge cases. The annotation already covers the safety profile, so the description is adequate but not enriched.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It efficiently communicates the action and resource without padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a fully documented input schema, an output schema present, and a readOnlyHint annotation, the description is sufficient for an agent to understand the tool's purpose and invoke it correctly. No additional context is needed for this simple getter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents each parameter fully. The description adds no additional meaning beyond referencing a 'specific color correction node', which loosely maps to node_index but does not enhance the schema's clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and a clear resource ('label of a specific color correction node'), making it distinct from sibling tools like color_set_node_label (set) and color_get_num_nodes (count). It unambiguously states the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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, no prerequisites, and no exclusions. It is a bare statement of functionality without contextual usage hints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry full burden. It only states the operation ('Set') and target, but does not disclose side effects (overwriting existing values), requirements (open timeline, valid item), or reversibility. This is insufficient for a mutating tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single, direct sentence with no superfluous words. Every word adds clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The presence of a detailed schema and output schema reduces the burden, but the tool is part of a complex color-grading context with many sibling tools (color_get_cdl, color_set_lut, cdl_write). The description does not explain prerequisites like the need for an open timeline or how this differs from cdl_write. With no annotations, some behavioral gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for all parameters, including the CDL dictionary structure. The description adds no extra parameter-level meaning, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Set') and resource ('ASC CDL values') and identifies the target scope ('on a timeline item's current node'). This clearly distinguishes it from siblings like color_get_cdl (reading) and color_set_lut (different color operation).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the context of color grading operations on a timeline item's current node, but does not explicitly mention when to prefer it over alternatives like color_get_cdl or cdl_read. Context is clear but no exclusions provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
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 it deletes a file and returns a boolean indicating success, but does not mention permission requirements, reversibility, or behavior when the file does not exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The description is efficiently structured and front-loaded with the verb.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple deletion tool, the description provides the core behavior and return value. However, it omits parameter semantics and any error/edge cases, which is acceptable for a simple tool but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter 'name' with no description and 0% coverage. The description does not clarify the expected format (e.g., extension included, path requirements), leaving the agent to infer the meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete an installed DCTL file' uses a specific verb and resource, clearly distinguishing from sibling tools like extension_remove_fuse and extension_remove_script.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use versus alternatives like extension_write_dctl or extension_list_dctl. Usage is implied by the clear delete intent, but no when-not-to-use or prerequisite conditions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds minimal context beyond this by specifying that it returns the display name and operates on timeline items, but it does not disclose any additional behavior such as error handling or required item state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the primary purpose. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only getter with a well-documented schema and an output schema present, the description fully conveys the tool's purpose and scope. No further information is necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% parameter description coverage, so the description does not need to add much. The description does not add any extra nuance beyond the schema, which is adequate for simple parameters with clear defaults and docstrings.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Return' and identifies the exact resource ('display name of a timeline item'), making it clear and distinct from sibling tools like item_get_duration or item_get_properties.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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, and there is no mention of any exclusions or prerequisites. It simply states what the tool does without contextual usage instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It states the core effect (enable/disable) and adds the 'muted/unmuted' nuance, but it does not disclose side effects, required permissions, reversibility, or behavior when item_name is ambiguous. This is adequate for a simple setter but not rich in 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that directly states the function. It is front-loaded and contains no filler, earning every word.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has four parameters, with track_type and track_index optional. The description does not explain when these are needed to disambiguate items with the same name across tracks, which could lead to incorrect invocation. The presence of an output schema covers return values, so that aspect is complete, but the disambiguation guidance is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema descriptions cover 100% of the parameters, so the baseline is 3. The description adds no additional meaning beyond the schema; the 'muted/unmuted' hint is also present in the schema's 'enabled' parameter description. Thus, the description does not compensate further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: enabling/disabling a timeline item, with the parenthetical '(muted/unmuted)' providing useful semantic context. This distinguishes it from sibling tools like timeline_set_track_enabled, which operate at the track level.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus alternatives, such as timeline_set_track_enabled or item_set_property. The implied usage from the name and description is clear enough for a simple setter, but there is no exclusionary or comparative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=true already establishes this as safe read operation. The description adds that the result includes the entire ffprobe payload, which is a useful scope disclosure, but it does not describe error behavior or performance characteristics. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states exactly what the tool does with no filler. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one well-documented parameter, an output schema, and a read-only annotation. The description fully covers the tool's behavior for an agent to invoke it correctly; no return-value explanation is needed given the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: the only parameter file_path is described as an absolute path to a media file. The description does not add parameter detail beyond the schema, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Return'), the resource ('full ffprobe payload'), and explicitly scopes the output to 'all format + stream fields'. This distinguishes it from siblings like media_probe, which may return a subset or processed output.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not mention when to use this tool versus alternatives such as media_probe, nor does it note any prerequisites, limitations, or exclusions. Usage is only inferred from the tool's purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavior. It explains that a Fusion clip wraps items into a composite that can be edited, but does not disclose side effects (e.g., whether original items are replaced or preserved), permissions, or failure modes. This is a moderate level of transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first front-loads the action, the second provides necessary context about what a Fusion clip is. Every sentence earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and lack of annotations, the description could be more complete. It does not clarify whether the operation is destructive to the timeline, what happens to the original items, or any prerequisites (e.g., an active timeline). Output schema presence reduces the need to explain return values, but behavioral gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 semantic value beyond the schema—'specific track' loosely maps to track_type/track_index, but no additional parameter behavior or constraints are explained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Create a Fusion clip from timeline items on a specific track.' This clearly states the tool's function and distinguishes it from sibling operations like timeline_create_compound_clip by explaining the Fusion-specific output.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case (wrapping selected items into a Fusion composition) but does not explicitly state when to use this tool versus alternatives (e.g., compound clips) or mention any prerequisites or exclusions. It provides context but no direct comparison.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is consistent with the readOnlyHint annotation and adds scope context ('all' and 'currently set'). However, it does not disclose return format, empty-result behavior, or error handling for nonexistent clips. The annotations cover the safety profile, and the output schema likely handles return shape, so this is acceptable but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no wasted words. Every word contributes to the purpose and scope, making it an appropriately minimal description for a simple getter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter, read-only tool with full schema coverage, an output schema, and readOnlyHint annotation, the description is largely complete. Minor gaps remain around flag-color semantics and edge cases (e.g., no flags set), but these are partially covered by the output schema and the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (clip_name: 'Name of the clip.'), so the baseline of 3 applies. The description does not add parameter-level meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Return') with an explicit resource ('all flag colors currently set on a clip'). It clearly distinguishes from sibling tools like clip_add_flag/clip_clear_flags (mutations) and clip_get_color (clip color vs. flag colors), so the 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 Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the read-only getter framing, but the description provides no explicit when-to-use or when-not-to-use guidance, nor does it name alternatives. For a simple single-parameter getter, the context is clear enough, but it lacks explicit exclusion or alternative direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It only states the action and scope, but does not mention error conditions (e.g., duplicate group name), required project state, permissions, or side effects. This is a significant gap 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence that is front-loaded with the verb and resource. Every word earns its place, with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and an output schema, the description adequately conveys the key scope ('current project'). It lacks detail on prerequisites (e.g., open project) but given the low complexity and presence of an output schema, it is mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides a complete description for the only parameter, group_name, with 100% coverage. The tool description adds no additional parameter semantics, so a 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Create' with resource 'color group' and scope 'in the current project', making it distinct from sibling tools like color_delete_group, color_get_group_list, and color_assign_to_group. It clearly states what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Create a new' implies usage for creating groups, and 'in the current project' provides clear context. It doesn't explicitly mention alternatives or when-not-to-use, but the action is self-explanatory and distinct from siblings. This meets the 'clear context, no exclusions' bar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true already indicating safety, the description adds the useful detail that it returns an empty string when no LUT is applied. However, it does not disclose behavior for invalid node indices or missing items, which would be valuable context beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundant words. It delivers the essential information efficiently and front-loads the verb and object clearly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given it is a simple read-only getter with complete parameter descriptions and an output schema, the description captures the core return behavior (path or empty string). It is complete enough for its complexity, though it could optionally mention edge-case behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the parameters are fully described in the schema. The description does not add any extra meaning to the parameters; it just references 'a specific node' generically. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Return the LUT file path') and a clear scope ('applied to a specific node'). It clearly distinguishes this from sibling tools like color_set_lut (which sets) and color_export_lut (which exports), making 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 Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its usage as a getter for a specific node's LUT path, but does not explicitly state when to use it over alternatives or provide any exclusions or prerequisites. For a simple read tool, this is adequate but lacks explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=true already declares this as a safe read operation, and the description matches that by describing a list operation. The description adds no further behavioral context (e.g., what it returns in edge cases, whether it can fail) beyond the annotation, which is acceptable for a simple read-only tool but does not exceed the annotation's coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the action and target. It contains no filler, repeated schema information, or unnecessary clauses, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only listing tool with a full output schema and read-only annotation, the description is mostly complete: it specifies the action and resource clearly. It does not mention the distinction between local and remote versions (via version_type), but the schema already documents that parameter, so the omission does not create a gap in operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema documents all four parameters with descriptions, achieving 100% schema_description_coverage. The description adds no extra parameter semantics (e.g., it does not explain how track_type or version_type affect results), so the baseline 3 is appropriate since the schema carries the full parameter burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (List) and the resource (all grade version names on a timeline item), immediately distinguishing it from sibling color version tools like color_get_version_count (which returns a count) and color_get_current_version (which returns the current version). The verb and object 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.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (when you need the names of all grade versions on a timeline item), but it does not provide explicit guidance about when to use alternatives such as color_get_version_count or color_get_current_version. No exclusions or prerequisites are mentioned, leaving the comparative usage context implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does disclose the persistent effect of writing source into the LUT directory. However, it does not mention overwrite behavior by default (though schema covers this), potential side effects, or any permissions/restrictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler, efficiently conveying the purpose and mechanism.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple three-parameter tool with full schema coverage and an output schema, the description provides the essential location and purpose. It could be slightly more complete with an explicit note about installing DCTLs vs. other extension types, but overall it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already well-documented. The description adds minimal extra meaning beyond linking 'source' to code and 'LUT directory' to the install location; it does not clarify filename defaults or overwrite nuances beyond what schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Install a DCTL') and the mechanism ('writing its source into the LUT directory'), making it distinct from related tools like extension_read_dctl, extension_list_dctl, and extension_remove_dctl.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when installing a DCTL from source), but it does not explicitly mention alternatives or exclusion cases, such as when to prefer extension_write_fuse or extension_write_script.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation destructiveHint=true already flags the destructive nature. The description adds useful context that the deletion is scoped to a Fusion composition within a timeline item, not the item itself, which is behaviorally informative beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, direct, and front-loaded with the action. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description, combined with the rich schema and existing annotations, provides sufficient context for this deletion tool. It covers the primary behavior and scope, though it omits explicit mention of optional targeting parameters (track_type, track_index), which are documented in the schema. Given the output schema exists, no return info is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions for all 4 parameters are present and clear (100% coverage), so the description adds minimal semantic value. The phrase 'by name' echoes the parameter names, providing no additional detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action (delete), the object (Fusion composition), and the location (from a timeline item). It distinguishes from sibling tools like fusion_rename_comp or fusion_add_comp by specifying deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The description simply states the action without mentioning alternative tools or conditions, leaving the agent to infer usage from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the agent knows this is safe. The description adds 'by name' but does not disclose what 'basic information' includes or any constraints beyond the schema. With annotations present, the bar is lower, but no additional behavioral context is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single well-structured sentence with no filler, front-loading the verb and resource. It is appropriately concise for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and readOnlyHint annotation, the description is sufficient for understanding the tool's core purpose. It lacks some context about how item_name relates to the composition, but overall it is adequate for a straightforward query tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are fully described. The description does not add any extra meaning beyond the schema, such as parameter relationships or usage nuances, which keeps it at the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns basic information about a Fusion composition by name, using a specific verb and resource. This distinguishes it from sibling tools like fusion_get_comp_names (lists names) and fusion_get_comp_count (counts compositions).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus alternatives. The purpose implies it is for querying details of a single composition, but no alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the scope ('all compositions on a timeline item') but does not disclose behavior for edge cases (e.g., missing items, empty results, or track resolution). Does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence that front-loads the action and resource. No wasted words or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, an output schema exists, and annotations are present, the description is sufficiently complete for a list operation. It could mention what happens when no compositions exist, but this is likely covered by the output schema. Minor gap: doesn't explicitly state the return type beyond 'names'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, meaning all three parameters (item_name, track_type, track_index) have their own descriptions in the schema. The tool description adds no additional parameter semantics beyond that, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and clearly identifies the resource ('names of all Fusion compositions') and scope ('on a timeline item'). It effectively distinguishes from siblings like fusion_get_comp_count (which counts compositions) and fusion_get_comp (which gets a specific composition).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly indicates usage by its action, but it does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites. It's a straightforward statement without comparative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
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 the mutation (create) and the target (Gallery), but adds no deeper context such as whether the new album becomes current, duplicates are allowed, or any required project state. Minimal but not misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no waste. Every word contributes to conveying the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create operation with one parameter and an output schema, the description adequately covers the core purpose and location. However, the absence of annotations leaves minor side effects unaddressed, but the simplicity of the tool makes this acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the single 'name' parameter is fully documented in the schema. The description adds no additional meaning beyond what the schema already provides, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Create') with a clear resource ('new still album') and location ('in the Gallery'). It clearly distinguishes from sibling tools like gallery_delete_album and gallery_set_current_album.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when you need to create an album, but provides no explicit guidance on when to use this tool versus alternatives or any exclusions. The purpose is clear enough to infer usage, but no direct comparison to siblings is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description 'List' is consistent with that. The description adds the PowerGrade album scope, which is useful context, but it does not disclose any additional behavioral traits such as behavior on missing albums, ordering, or whether it reads from the current album context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that immediately conveys the purpose. Every word earns its place, and there is no redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one clearly described parameter and an output schema, the description plus schema is sufficient. It lacks only minor context such as error behavior or relationship to current PowerGrade album, but these are not essential given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: the single parameter album_name has a description ('Name of the PowerGrade album.') that fully explains its meaning. The tool description adds no additional parameter semantics, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List'), the resource ('stills'), and the scope ('PowerGrade album'), which distinguishes it from the sibling tool gallery_get_stills. The tool name and description align perfectly, leaving no ambiguity about its function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving stills from a PowerGrade album, but it does not explicitly state when to use this tool instead of gallery_get_stills or other gallery tools. No alternatives or exclusions are mentioned, so the guidance is only implied by the scope.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. It states the switch operation but omits failure conditions (e.g., album not found) and any side effects. This is a minimal mutation description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the verb, no redundant text, and completely sized for the simple operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple operation, one parameter fully described, and presence of an output schema, the description covers the essential purpose and argument. It doesn't elaborate on preconditions, but the schema hints at exact match requirement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a descriptive parameter; the description's '*album_name*' adds no semantic value beyond the schema's 'Exact name' description, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Switch' with the resource 'active still album' and the parameter 'album_name', clearly distinguishing it from siblings like gallery_set_current_powergrade_album and gallery_get_current_album.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'active still album' provides clear context that this tool is for still albums, not powergrades. It doesn't explicitly exclude alternatives, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must convey behavioral traits. It states the operation (switch active album) and the target, but doesn't disclose side effects, error handling if the album doesn't exist, or whether it's a safe reversible operation. It adds basic transparency beyond the schema but misses important context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It clearly states the action and the parameter in a compact form.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple one-parameter setter nature and an existing output schema, the description is adequate. It doesn't explain prerequisites like an open project, but the simplicity and schema coverage reduce the need. A small gap remains around error behavior, but overall it's complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description covers the parameter fully ('Exact name of the target PowerGrade album'), and the description only restates the parameter's role without adding extra meaning. Baseline 3 applies due to 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Switch' with a clear resource 'active PowerGrade album' and the target is defined by the parameter. It clearly differentiates from sibling gallery_set_current_album by specifying PowerGrade, matching the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for PowerGrade albums, but it doesn't explicitly mention alternatives or when to use this over gallery_set_current_album. The guidance is largely inferred from the tool name and parameter rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The destructiveHint annotation already indicates this is a destructive operation. The description adds no extra behavioral context beyond that, such as behavior when the marker does not exist or whether the deletion is reversible. It does not contradict the annotation, but it does not enrich it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that states the essential purpose without any extraneous words. It is front-loaded and easy to process.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation, the description is adequate. It explains what it does and the schema covers all parameters. The presence of an output schema means return values need not be explained. It lacks mention of edge cases (e.g., missing marker), but that is not critical for a basic tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all four parameters described. The description does not add additional meaning to the parameters beyond what the schema already provides, so a 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete the marker at a specific frame offset on a timeline item' clearly states the action (delete), the resource (marker on a timeline item), and the qualifier (specific frame offset). It distinguishes itself from sibling tools like clip_delete_marker and timeline_delete_marker by specifying 'timeline item'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for timeline items but does not explicitly mention when to use this tool versus alternatives such as clip_delete_marker or timeline_delete_marker. There are no exclusions or alternative suggestions, so the guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint already indicating a safe read operation, the description adds the example of audio for video clip, but does not disclose behavior like handling of multiple linked items, absence of links, or track-specific semantics beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that efficiently conveys the core function and includes a clarifying example. No filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with a full schema, an output schema, and a clear example, the description is nearly complete. It could be more explicit about the full scope of 'linked' (e.g., multi-track links), but the provided context is likely sufficient for correct use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already well-documented. The description's example loosely hints at track_type usage but adds no substantial meaning beyond the schema's parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Return') and resource ('items linked to this timeline item'), with a concrete example ('audio for a video clip') that clarifies the purpose and distinguishes it from sibling item_* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when needing linked items, but provides no explicit when-to-use guidance, exclusions, or comparison to alternative tools. The example gives context but not decision criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full burden of behavioral disclosure. It states the action but does not explain what happens on success, whether duplicate names are allowed, or if the new folder becomes current. For a mutation tool, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the action, and contains no wasteful language. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter create tool, the description adequately states the core function. The output schema presumably covers return values, and the location context (current folder) is clear. It lacks preconditions or error handling details, but these are less critical for such a simple operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides a description for the 'name' parameter (100% coverage). The tool description adds no additional parameter semantics, such as naming constraints or whether slashes create nested folders, so it meets the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create' and the resource 'subfolder', with important context 'inside the current Media Pool folder'. This distinguishes it from sibling tools like media_pool_delete_folders or media_pool_import_media.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: it is used to create a subfolder in the current Media Pool folder. It does not explicitly mention alternatives or exclusionary guidance, but the tool's unique purpose among siblings makes usage obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description provides basic behavioral info: creates an empty timeline in the current folder. However, it does not disclose side effects (e.g., whether the new timeline becomes current), failure modes, or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single, focused sentence with no filler. Front-loaded with the action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter and an output schema, the description is adequate to select and invoke. It could mention that the timeline may become current, but that's not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers the single 'name' parameter with a clear description. The tool description does not add additional meaning beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 'create' and resource 'new empty timeline' with location 'current Media Pool folder', clearly distinguishing it from siblings like media_pool_create_timeline_from_clips and media_pool_create_folder.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies usage in the current media pool context but does not explicitly mention alternatives or exclusions, such as using media_pool_create_timeline_from_clips when clips are available.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose side effects and prerequisites. It only states the basic creation action and the clip source, omitting important behavioral details such as whether the new timeline becomes the current one, how duplicate names are handled, or what happens if a clip is not found. This is a significant gap for a creation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise, front-loaded sentence with no redundancy or filler. Every word contributes to conveying the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter creation tool with full schema coverage and an output schema, the description is adequate. It covers the essential action and source context, but the lack of annotations means the agent still lacks safety/prerequisite information. Still, given the tool's simplicity, this is decently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides full descriptions for both parameters: name and clip_names, including the note that clips are searched in the current Media Pool folder. The description adds no additional parameter-level information beyond what the schema supplies, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Create a new timeline') and the distinctive detail 'populated with specific clips from the current folder.' This differentiates it from sibling tools like media_pool_create_timeline (which likely creates an empty timeline) and timeline_append_clips (which appends to an existing timeline).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use this tool when you need a new timeline composed of specific clips already in the current folder. It does not explicitly name alternatives or state when not to use it, but the context is unambiguous enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It states the core action but does not mention side effects (e.g., does it stop playback?), prerequisites (e.g., an open project/timeline), or error handling for invalid timecodes. While not misleading, it leaves these aspects unaddressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence that is front-loaded with the verb 'Move' and the object. No wasted words, perfectly scoped.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple setter with one well-documented parameter and an output schema, the description is adequate. It provides enough context for an agent to invoke it correctly, though it could mention prerequisites like an open timeline, but that is likely implied by the playback context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage for the sole parameter is 100%, with a clear description and example. The tool description adds no extra parameter semantics, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Move the playhead') and the target resource ('to a specific timecode position'). It is distinct from sibling tools like playback_get_timecode, which retrieves the current timecode, making this the setter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (to set the playhead to a timecode), but it does not explicitly contrast with alternatives such as playback_get_timecode or page navigation. There is no clear 'when to use' or 'when not to use' guidance beyond the obvious setter semantics.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosure. It does state the return value ('True if navigation to root succeeded') and the action's effect (navigate to root). However, it does not describe side effects like changing the current folder, failure behavior, or behavior when already at the root.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of two short sentences that state the action and the return value. Every word earns its place with no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter navigation tool with an output schema, the description is adequately complete. It names the target location and the success return value. Minor gaps exist around edge cases, but the simplicity of the operation makes this sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is no parameter semantics to clarify. The baseline of 4 applies as the description need not explain a non-existent parameter set.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Navigate to the root of the project database') with a specific verb and resource. It is distinct from sibling tools like project_folder_goto_parent, which targets the parent folder rather than the root.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives such as project_folder_goto_parent or media_pool_get_root_folder. The description simply states the action without contextual cues or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already communicates the read-only nature. The description adds minimal context beyond 'single' and 'by its key', which clarifies the scope but does not disclose additional behavioral traits such as error handling or return format. Since annotations cover safety, a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one concise, clear sentence with no wasted words. It effectively front-loads the core purpose and parameter information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with a single parameter and an output schema exists, so the description does not need to explain return values. The description is sufficient for a getter, though it does not mention potential error or missing-key behavior. Overall, it is adequately complete for the complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the schema already providing examples and meaning for the 'key' parameter. The description's 'by its key' adds no new semantic information beyond what the schema offers, 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Read') and the resource ('a single project setting'), and mentions the parameter ('by its key'). This distinguishes it from siblings like project_set_setting (write) and timeline_get_setting (different resource).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for reading a project setting, but does not explicitly state when to use this tool versus alternatives. No exclusions or alternative tool references are provided, making the 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.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description is the only source of behavioral disclosure. It only states the core import action but does not mention potential side effects such as overwriting existing projects, whether the current project is closed, or any permission requirements. This is minimal disclosure for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word is necessary and efficiently communicates the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter with full schema description) and an existing output schema, the description is largely sufficient. However, it does not explain the prerequisite of an open database folder or any implications of importing, which could be inferred from the context but is not stated. Still, it is adequate for a basic import command.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with file_path described as 'Absolute path to the .drp file to import.' The description adds no additional parameter semantics beyond the schema, so a 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Import' with the resource '.drp project file' and destination 'current database folder', making it clear and distinct from sibling tools like project_open or project_export. It fully conveys what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context of the operation—importing into the current database folder—which implies a prerequisite of having a folder open, but it does not explicitly mention alternatives or when not to use this tool. This gives clear usage context without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description accurately reflects a read-only operation, consistent with the readOnlyHint annotation. It does not add deeper behavioral details (e.g., error handling if format is invalid, or whether results depend on project settings), but annotations already cover the safety profile, so this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no redundant wording. It immediately states the action and the object, making it concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, single-parameter read-only tool with a rich schema and output schema, the description is sufficiently complete. It covers the core behavior, while the schema supplies parameter details and the output schema handles return structure. The only minor gap is the lack of explicit mention of potential error conditions, but this is not critical given the low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter, providing example values and a pointer to render_get_formats(). The tool description itself adds no additional parameter semantics, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it returns available codecs for a given render format, specifying both the action and the resource. This distinguishes it from sibling tools like render_get_formats (which returns formats) and render_get_format_and_codec (which returns the current format/codec pair).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage is implied: you need to know codecs for a specific format. The parameter description suggests using render_get_formats() to obtain valid format names, providing a weak cross-reference. However, there is no explicit guidance on when to prefer this tool over related siblings such as render_get_format_and_codec, nor any exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It discloses the return value (new timeline name or None), but does not mention whether the duplicate becomes current, potential naming conflicts, or any side effects on the original timeline. This gap for a mutating operation is notable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences covering the action and the return value. Every word earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with an output schema, the description covers the essential behavior (duplicate current timeline) and the failure case (None). It lacks a few details about state changes, but overall it is sufficiently complete for a simple operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes no parameters, so schema coverage is effectively 100%. The description adds value by explaining the return semantics (new name or None), which is useful beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Duplicate the current timeline') with a clear resource and outcome. It is unambiguous and differentiates from sibling tools like timeline_create_compound_clip or timeline_get_setting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The use case is implicitly clear—call when you want to duplicate the current timeline—but no explicit guidance is given about when not to use it or alternatives (e.g., creating a new timeline manually). No prerequisites or side exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=true already conveys the read-only nature. The description adds the 1-based indexing convention, which is useful, but does not disclose other behavioral traits such as error behavior for out-of-range indices or what 'info' includes. This is acceptable given the output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It conveys the essential information efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 param and an output schema, the description is sufficient. It does not need to list return fields because the output schema exists, and the read-only hint is annotated. The only minor gap is the lack of explicit usage guidance, but the overall context is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already explains '1-based position of the timeline in the project.' The description merely repeats '1-based index' without adding new meaning or context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Return info') and clearly identifies the resource ('a timeline') and the selection mechanism ('at the given 1-based index'). This distinguishes it from sibling tools like timeline_get_current or timeline_get_count.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have an index (1-based), but it does not explicitly state when to prefer this over alternatives (e.g., timeline_get_current) or provide exclusionary guidance. The usage context is inferred from the parameter description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already signals a safe read operation, and the description's 'Return' agrees. However, the description adds no further behavioral context such as error handling, return format, or dependency on timeline state beyond what the annotation and simple verb already convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no redundant words or filler. It front-loads the action and resource, making it immediately understandable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple getter with two well-documented parameters and an output schema, the description is sufficiently complete. It identifies the object (track) and scope (current timeline) without over-explaining. Minor gaps like error behavior are not critical for this tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides full descriptions for both parameters: track_type lists the allowed values and track_index defines it as 1-based. Since schema coverage is 100%, the description does not need to add extra parameter detail, and the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Return the name'), the resource ('a specific track'), and the context ('in the current timeline'). It uses a specific verb and noun combination that distinguishes it from siblings like timeline_set_track_name and timeline_get_track_count.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when you need a track's name) but does not explicitly mention alternatives or when not to use it. Sibling tool names suggest related operations, but the description itself provides no exclusion or alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=true already indicates a safe read operation. The description adds value by specifying the return type (a label color string) and giving concrete examples, which goes beyond the annotation. No contradictions are present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately states the action and object. It contains zero filler and every word contributes to understanding the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only getter with one well-documented parameter and an output schema present, the description is complete. It explains what is returned and the target resource, and no additional behavioral information is necessary for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the only parameter clip_name as 'Name of the clip.' (100% schema coverage). The description adds no additional semantics for the parameter, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Return') and specifies the exact resource ('label color assigned to a clip') with example values ('Orange', 'Blue'). This clearly distinguishes it from siblings like item_get_color or clip_set_color by emphasizing 'label color'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given for when to use this tool versus alternatives. For instance, it does not clarify that this is for clip labels in the media pool, unlike item_get_color which likely applies to timeline items. The description is purely functional with no context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already establishes this as a safe read operation, and the description does not contradict it. However, it adds no extra behavioral context such as behavior on missing items, edge cases, or return format specifics. With annotations present, this meets the minimum viable standard.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the essential purpose with zero wasted words. It is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, has full schema coverage, an output schema (per context signals), and a readOnly annotation. The description sufficiently covers what the tool does without needing to explain return values, as the output schema exists. No pending questions about the tool's behavior remain unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all three parameters (item_name, track_type, track_index), so the schema carries the full burden. The description adds no parameter-level detail beyond what the schema already provides, maintaining the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the number of Fusion compositions on a timeline item, using a specific verb ("Return the number") and resource ("Fusion compositions on a timeline item"). It differentiates from sibling tools like fusion_get_comp_names and fusion_get_comp by focusing on the count.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given on when to use this tool versus alternatives, but the purpose is straightforwardly implied by the name and description—use it when you need the count of compositions. It lacks explicit exclusions or alternative recommendations, placing it at the 'implied usage' level.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already signals this is a safe read operation; the description adds the specific return values (start frame, end frame, duration), which is useful context. But it does not disclose behavior for invalid/missing item names, track types, or index boundaries, and it doesn't explain the frame origin (0-based vs 1-based). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that immediately states the tool's purpose and returned data. Every word earns its place, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple getter with an output schema and full parameter documentation, the description is sufficiently complete. The tool has low complexity, and the combination of description, schema (100% coverage), and readOnlyHint leaves no major gaps in understanding what the tool does and how to call it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, and the schema already explains item_name, track_type, and track_index. The description adds no additional parameter detail beyond the schema, such as how item_name relates to timeline context or how track_type/track_index affect lookup. It does not compensate for or expand on the schema's meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Return') and resource ('timeline item') and clearly states the exact data returned: start frame, end frame, and duration. This distinguishes it from sibling tools like item_get_duration, which only returns duration, and item_get_properties, which returns a broader set of properties.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: any time you need start, end, or duration of a timeline item. However, it does not explicitly state when to prefer this over item_get_duration or item_get_properties, nor does it mention any exclusions or alternative tools. No explicit 'when' or 'when-not' guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The destructiveHint annotation already signals that this tool deletes data, and the description adds 'from the queue' which is part of the purpose rather than additional behavioral context. It does not disclose any extra effects (e.g., irreversibility, whether a running job can be deleted). With annotations covering the destructive nature, the description adds minimal value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately states the tool's purpose. No unnecessary words, well-structured, and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter tool with an output schema present, the description is sufficient. It states the action and target, and the schema covers parameter details, so no additional context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with a clear description of job_id, including how to obtain it. The tool description adds no further parameter meaning, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Delete') and resource ('specific render job from the queue'), clearly distinguishing it from the sibling tool render_delete_all_jobs. It precisely states the scope and action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies use for a single job deletion but provides no explicit guidance on when to use this versus render_delete_all_jobs. No exclusions or alternative references are given, so usage is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the 'media files' scope, but does not disclose any additional behavioral traits such as listing order, pagination, or permission requirements. The readOnlyHint annotation already covers safety, so the bar is lower; the description adds little beyond that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately states the primary action and resource. There is no wasted wording, and it is appropriately front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a simple one-parameter tool, the schema fully documents the parameter, annotations cover safety, and an output schema exists for return values. The description fully conveys the tool's purpose without needing further elaboration.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter folder_path, which is well-described in the schema. The description does not add extra detail about the parameter, so it provides no value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' with a clear resource 'media files in a storage folder'. This clearly distinguishes it from sibling tools like storage_get_subfolders (which lists folders) and storage_get_volumes (which lists volumes).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The context implies usage for listing media files, but there is no explicit guidance on when to use this versus alternatives like storage_get_subfolders. No exclusions or alternative mentions are provided, leaving the agent to infer based on the name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns with the readOnlyHint annotation by stating it returns a count, adding the scope 'current project.' It does not disclose handling of empty projects, return format specifics, or potential errors, but the annotation already covers the read-only nature, lowering the bar.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no filler or redundancy. It is appropriately concise for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple count operation with no parameters and an output schema, the description provides sufficient context: the scope (current project) and the result (number of timelines). No additional details are necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters, the schema is fully complete. The description adds clarity by specifying what is counted (timelines) and the scope (current project), though no parameter explanation is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 number of timelines in the current project.' It identifies a specific verb and resource, and the scope 'current project' distinguishes it from sibling timeline tools that operate on individual timelines or settings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like timeline_get_by_index or timeline_get_current. The description implies a use case for counting timelines but does not explicitly state conditions or mention alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description is consistent. It adds behavioral detail beyond annotations by specifying 'first' (i.e., only the first correction is returned, not all) and the file extensions .cdl/.ccc, which are not in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no filler words. It conveys the core functionality and scope efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter, a read-only annotation, and an output schema (not shown but present). The description covers the essential behavior (reading the first CDL) and the input file type, making it complete for typical use, though it does not address edge cases like missing corrections.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with file_path described as 'Absolute path to an ASC CDL file.' The description does not add parameter-level details, but the schema already fully documents the only parameter, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Read') and identifies a clear resource ('the first ASC CDL correction from a .cdl/.ccc file'). It distinguishes from siblings like cdl_read_all by specifying 'first' and the file format.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied: reading a CDL correction from a file. However, it does not explicitly state when to use this over cdl_read_all or color_get_cdl, and no alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The destructiveHint annotation already indicates the operation is destructive. The description adds context by specifying the resource (proxy media link) and the target (clip), but it does not disclose whether the proxy file itself is deleted or if any other side effects occur. This is adequate with annotation support but not richer.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence (7 words) that is front-loaded and contains no unnecessary words. Every word contributes to conveying the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple tool with one parameter, and the schema documents that parameter fully. An output schema exists, so return values need not be explained. The description plus annotations provide enough context for correct usage, though slightly more detail about side effects could elevate it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter description ('Name of the clip whose proxy link to remove') is already explicit. The tool description adds no additional meaning beyond what the schema provides, 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Remove') and resource ('proxy media link') with a clear object ('from a clip'). It directly explains the tool's function and is easily distinguished from the sibling tool clip_link_proxy, which performs the inverse operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the usage context: when a proxy link needs to be removed from a clip. It doesn't explicitly mention alternatives or exclusions, but the operation is obvious given the sibling tool clip_link_proxy. This meets the 'clear context, no exclusions' level.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The destructiveHint annotation already signals destructive behavior. The description adds that the deletion is scoped to the current project and requires an ID, but does not disclose potential side effects (e.g., whether associated clips are unassigned). It remains consistent with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single, direct sentence with no redundancy or filler. Every word contributes to clarifying the action and scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with one parameter and a destructive annotation, the description is nearly complete. It clearly states what is deleted and where, though it does not mention reversibility or error conditions—likely covered by the output schema and annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the group_id property already includes a clear description with guidance to obtain IDs from color_get_group_list(). The tool description adds no additional parameter semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Delete') and resource ('color group') with a clear scope ('from the current project'), fully distinguishing this from siblings like color_create_group and color_get_group_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly conveys when to use it (when a color group needs deletion) and clarifies the context ('current project'). However, it does not explicitly mention alternatives or exclusions, though the operation is self-evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/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 that it lists scripts with specific extensions and in a subfolder, but does not disclose further behavior such as recursion, sorting, or output structure. With annotations covering the safety profile, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the verb and object immediately. Every word earns its place; there is no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with one optional parameter, an output schema, and a read-only annotation, the description is fairly complete. It could be improved by explicitly stating how 'category' maps to subfolders, but the schema description covers the allowed values, so this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage with a description listing allowed values ('Comp, Edit, Color, Fairlight, Deliver, Utility'). The tool description adds the concept of a 'Fusion Scripts subfolder', implying that the 'category' parameter selects the subfolder, which gives extra meaning beyond the schema's list of values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' with a clear resource ('scripts') and narrows scope with file extensions ('*.lua' / '*.py') and 'Fusion Scripts subfolder'. This clearly distinguishes it from sibling tools like extension_list_dctl and extension_list_fuses, which list other file types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through its verb and object, but does not explicitly state when to use this tool versus alternatives like extension_get_paths or extension_list_fuses. There is no mention of 'when not to use' or alternative tools, so the guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavior. It reveals mutation and return value but omits failure conditions, whether an existing composition is replaced, undo/save implications, or required permissions. This is a significant gap 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three short paragraphs, front-loaded with purpose, no redundant content. Every sentence earns its place: purpose, prerequisite, return value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-param tool, covers operation, target, prerequisite, and return value. Lacks edge-case info (e.g., no item selected) but mostly complete. Output schema exists, so return value explanation is a bonus.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters; schema coverage is 100%. Baseline 4 applies since there are no params to describe. The description adds implicit target context but no parameter-level details needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States specific verb+resource: 'Add a new Fusion composition to the timeline item under the playhead.' This distinguishes it from siblings like fusion_import_comp (import) and fusion_insert_title via the timeline item target.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit prerequisites: operates on selected item, position playhead first. Does not mention alternatives or when-not-to-use, but for a zero-parameter tool this is sufficient contextual guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It reveals important behavior (append at end, uses AppendToTimeline API, mediaType 'title'), but does not mention prerequisites like an open project/timeline, side effects, or error conditions. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the primary action and followed by a useful implementation detail. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one parameter, output schema present). The description explains the action and placement sufficiently, but misses explicit callouts for required setup (e.g., timeline must exist) and does not mention what the tool returns. Overall, adequate for the complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for the single parameter, including examples ('Text+', 'Scroll'). The description adds no extra meaning, 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Insert a Fusion title') and the target resource ('into the current timeline'), with a specific placement detail ('appended at the end'). This distinguishes it from similar tools like fusion_insert_generator and timeline_append_clips.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies usage context by specifying 'current timeline' and the mediaType, but does not explicitly compare with alternatives or state when not to use it. Clear context but no exclusions makes this a 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide destructiveHint: true, so the destructive nature is covered. The description adds the context that it's specifically a 'still album' but does not disclose additional behavioral details such as whether contained stills are deleted or if the operation is permanent. With annotations in place, this is adequate but not enriched.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, complete sentence that is immediately understandable and front-loaded with the action and object. No filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter destructive operation with an output schema and a clear annotation, the description is largely sufficient. It could have mentioned side effects like deletion of contained stills, but the combination of schema and annotations covers the essential context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter album_name is fully described in the schema ('Name of the album to delete'), and the description adds no extra semantic value. With schema description coverage at 100%, 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Delete') and resource ('a still album from the Gallery'), clearly distinguishing it from sibling tools like gallery_delete_stills (which deletes stills, not albums) and gallery_create_album (which creates). The phrase 'still album' also differentiates from powergrade albums.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use it (when you need to delete a still album), and the resource type naturally distinguishes it from gallery_delete_stills and gallery_get_albums. However, it does not explicitly state alternatives or exclusions, so it stops short of a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It clearly discloses a destructive side effect ('removing other take options'), which is critical behavioral information. However, it doesn't mention reversibility, return value, or any preconditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. The first sentence states the purpose, the second explains the consequence. Perfectly front-loaded and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool with three well-documented parameters and an output schema, the description adequately covers the main behavior. It lacks niche context like whether it only works when multiple takes exist, but overall it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% description coverage for all three parameters. The tool description adds no additional parameter-specific meaning, so a 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Finalize' and clearly states the resource ('timeline item') and the key effect ('commits the current take, removing other take options'). This distinguishes it from sibling take operations like select or delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you want to commit the current take and discard alternatives, but it does not explicitly contrast with item_select_take_by_index or item_delete_take_by_index. No clear when-to-use vs alternatives is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already covers safety. The description adds that it runs ffmpeg's silencedetect filter, which provides some implementation context, but does not disclose output details (though an output schema exists). This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and every word adds value. It includes a helpful parenthetical and implementation note without any fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward read-only analysis tool with full schema coverage and an output schema, the description provides sufficient context. It could mention prerequisites like needing an audio track, but that is minor given the available structured data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and each parameter has a clear description. The tool description adds no additional parameter semantics beyond what the schema already provides, 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool detects silent spans in audio, with specific use cases (dead air, sync gaps). It distinguishes itself from sibling tools like media_detect_black by explicitly scoping to audio.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context ('dead air, sync gaps') implying when to use it, but does not mention any alternatives or exclusions. It is clear enough for an agent to infer its purpose relative to other media detection tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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 a key safety guarantee: 'Source media is never modified.' It also explains the sampling behavior (evenly-spaced, fps overrides count). While it does not mention potential file overwrites or directory creation, it gives substantial behavioral context beyond the bare operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the primary purpose. It uses only two short sentences to convey core functionality, parameter selection logic, and safety behavior. No redundant or irrelevant content; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists, the description need not explain return values. It covers the tool's core behavior, parameter semantics, and safety characteristics. It omits edge-case behavior (e.g., overlapping output files), but overall it provides sufficient context for a 4-parameter tool with clear schema support.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% parameter coverage, including descriptions for fps, count, file_path, and output_dir. The description reiterates the count/fps relationship already present in the schema descriptions, adding no new parameter-level detail. Baseline score of 3 applies since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Extract multiple frames to an output directory for review.' It clearly distinguishes from the sibling tool media_extract_frame by emphasizing 'multiple frames'. The scope (output directory) is also stated, leaving no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance on choosing between count and fps parameters, explicitly stating that fps overrides count and count is default. However, it does not explicitly address when to use this tool versus the sibling media_extract_frame, leaving that to be inferred from the word 'multiple'. Thus usage guidance is implied rather than explicit about alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
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 immediate-open behavior, which is a useful behavioral trait, but it doesn't mention side effects like what happens to the current open project or failure behavior if the name already exists (though schema mentions uniqueness). Gaps remain.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that is front-loaded with the primary action and includes only the additional behavior (opens immediately). No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, clear schema, and output schema present), the description is largely complete. The only minor omission is clarifying the effect on any currently open project, but the phrase 'open it immediately' strongly implies it becomes the active project.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is one parameter (name) with 100% schema description coverage, so the schema already carries the parameter meaning. The description does not add additional context about the parameter, which matches 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.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Create') and resource ('project'), and adds the distinct behavior 'open it immediately,' which clearly separates it from siblings like project_open (which opens existing projects) and project_import. This is a precise and unambiguous purpose statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates when to use the tool: when creating a new project and wanting it opened immediately. It doesn't explicitly mention alternatives or when not to use it, but the context is clear enough given the sibling set and the action-oriented phrasing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=true already signals a safe read operation. The description adds value by revealing the return shape (dict with DbType, DbName, IpAddress) and the conditional behavior of IpAddress appearing only for remote databases. This goes beyond the annotation, providing useful contextual detail. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using two short sentences. The main action is front-loaded, and the return format is separated clearly with a 'Returns:' line. Every word earns its place, with no repetition or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (no parameters, read-only, simple output schema), the description is sufficiently complete. It covers the purpose and return shape. A minor gap is the lack of mention of what happens when no project is open, but this is a simple getter and the output schema already documents the return type, so the description does not need to explain more.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, and the input schema is empty with 100% coverage. The rubric sets a baseline of 4 for parameterless tools. The description appropriately does not attempt to explain parameters, since there are none.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Return info') and the specific resource ('current project database'). It distinguishes from the sibling tool 'project_get_database_list' by explicitly scoping to the current database, and also specifies the return format, 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 Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives such as 'project_get_database_list'. The word 'current' implies a prerequisite (an open project), but this is not stated, and there is no discussion of exclusions or alternative scenarios. The description focuses purely on what it does, not when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already flag destructiveHint=true, so the description's added value is the return semantics: 'True if all jobs were deleted successfully.' However, it does not disclose partial-failure behavior (e.g., what happens if some jobs fail to delete) or whether rendering must be stopped beforehand.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the action ('Delete all render jobs from the queue') followed by the return condition. 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/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter destructive tool with a destructiveHint annotation and output schema, the description covers the core behavior and return value concisely. It leaves minor gaps around partial failure or stopping renders, but these are not critical for such a simple operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters in the schema, so the description needs to explain none. The baseline of 4 applies because the tool correctly requires no input; the description adds no extra parameter information, but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Delete all render jobs from the queue' with a specific verb, resource, and scope. The word 'all' clearly distinguishes this from the sibling render_delete_job, which deletes individual jobs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage is implied by the phrase 'all render jobs' — an agent can infer this clears the entire queue — but there is no explicit guidance on when to use this vs. render_delete_job, nor any mention of prerequisites like stopping active renders first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
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 applies the preset's settings, implying a state-changing operation. However, it does not mention whether current settings are overwritten, behavior on invalid names, or any return value, though the presence of an output schema reduces the need for return details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the action and result with no wasted words. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one parameter, well-documented schema, output schema exists). The description fully conveys the primary action. It lacks only an explicit statement about side effects or prerequisites in the main description, but the schema covers the prerequisite.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a helpful parameter description ('Exact name of the preset. Get valid names from render_get_presets()'). The main tool description adds no parameter-level information, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Load' with a clear resource 'render preset' and mechanism 'by name, applying its settings'. It distinguishes itself from sibling tools like render_get_presets (which lists presets) and render_set_settings (which sets individual settings).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The main description implies usage (when you want to load a preset), and the schema for preset_name explicitly directs the agent to render_get_presets() for valid names, providing a clear prerequisite. However, it does not explicitly discuss alternatives or exclusions, such as when to use render_set_settings instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The destructiveHint annotation already flags destructiveness, and the description adds the behavioral detail that deletion is scoped by item name and track. This clarifies 'what gets destroyed' (timeline items) and how selection works, which is helpful context beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence with no unnecessary words. The verb is front-loaded, and the sentence covers what, how, and where in a compact manner.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward delete operation, the description, combined with the full schema and destructiveHint annotation, is sufficient. An output schema exists, so return values are not the description's responsibility. It lacks only optional details like behavior when items are not found, but these are not critical for a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already well-documented. The description only paraphrases 'by name' and 'specific track' without adding new details about format, edge cases, or relationships between parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Delete') with a clear resource ('timeline items') and scope ('by name from a specific track'). This distinguishes it from sibling tools like timeline_delete_track (deletes whole tracks) and media_pool_delete_clips (deletes media pool clips), making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (deleting timeline items by name from a specific track) but does not explicitly mention alternatives or exclusions. It does not say when not to use it or point to sibling tools like item_delete_take_by_index, leaving some room for interpretation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already signals a non-mutating operation, and the description adds useful scoping context (current timeline, track type). However, it does not disclose nuances like whether disabled/locked tracks are included, though this is minor for a simple query.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently conveys purpose and scope without any redundant or extraneous wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only count tool with a fully documented parameter and an output schema present, the description covers the essential context. It could explicitly mention that a current timeline must be active, but this is largely implicit given the sibling timeline tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents the single track_type parameter, including its default and allowed values. The description only refers to 'given type' and adds no additional parameter-level detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the number of tracks of a given type in the current timeline. It uses a specific verb and resource, distinguishing it from sibling tools like timeline_get_count (timeline count) and timeline_get_track_name (track names).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates the operation applies to the current timeline and requires a track type, but it does not explicitly state when to use this tool versus alternatives or mention any exclusions. Usage context is implied rather than fully spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the behavioral trait of reading 'every' correction and specifies the source file types, complementing the readOnlyHint annotation. It provides useful context without contradicting the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no wasted words. It is appropriately sized and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with a well-documented schema and an output schema, the description is complete. It clearly explains what the tool does and what input it expects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameter descriptions, so the description adds no additional parameter meaning beyond the baseline. The single parameter is well-documented in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Read') and resource ('every ASC CDL correction') and clearly identifies the file types (.ccc/.cdl). It distinguishes itself from the sibling 'cdl_read' by emphasizing 'every'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for reading all corrections from a file but does not explicitly mention alternatives or when not to use this tool. Differentiation from 'cdl_read' is only implicit through the word 'every'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint: true, establishing the read-only nature. The description adds a useful behavioral detail about return keys ('frame IDs as strings'), but does not cover error cases or ordering. This modest addition aligns with the lower bar set by 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly two sentences: the first states the primary purpose, and the second explains the key format. No redundant or irrelevant information is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple, single-parameter read tool with an output schema present. The description sufficiently explains what it returns and the key type; the output schema handles further return structure. No critical gaps exist for an agent to invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description for clip_name ('Name of the clip.') is complete, and schema coverage is 100%. The tool description does not add additional parameter guidance, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Return all markers on a clip.' This clearly distinguishes it from siblings like clip_get_flags (flags vs markers) and timeline_get_markers (clip vs timeline).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates the tool is for retrieving markers from a clip, providing context without explicit exclusions or alternatives. It does not mention when to prefer this over item_get_markers, but the 'on a clip' phrasing conveys the intended scope.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds context about the return format (key-value pairs) and scope (all metadata fields). This goes beyond the minimal annotation by clarifying what the agent can expect, without needing to cover safety since annotations handle that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the verb, and every word earns its place. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one simple parameter, full schema coverage, a read-only annotation, and an output schema present, the description is fully adequate. It does not need to explain return values since the output schema covers them.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with clip_name described as 'Name of the clip to inspect.' The description adds no extra parameter detail beyond the schema, 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/5Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Return' with resource 'clip' and clear scope 'all metadata fields as key-value pairs'. This distinguishes it from sibling tools like clip_get_name and clip_get_properties, leaving no ambiguity about the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when all metadata fields are needed, but it does not explicitly contrast with alternatives like clip_get_properties or provide when-not-to-use guidance. It is clear enough for basic selection, but lacks explicit differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, so the description doesn't need to repeat that. It adds the return value ('display name') but does not disclose error behavior, case sensitivity, or what happens if the clip does not exist. This is adequate for a simple getter but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is front-loaded with the verb and resource. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with a single well-documented parameter, a clear return value, and a readOnly annotation. The output schema likely provides return type details. No additional context is necessary for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter description already explains that clip_name is the current name. The tool description adds no extra meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Return) and the target (display name of a media-pool clip). It distinguishes from siblings like clip_set_name (setting) and item_get_name (timeline items) by specifying 'media-pool clip'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'media-pool clip' provides clear context for when to use this tool, distinguishing it from timeline item tools. However, it does not explicitly mention alternatives or exclusions, such as 'use item_get_name for timeline items'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already conveys safety, and the description is consistent but adds no extra behavioral detail (e.g., error handling, return format, or which track/timeline is referenced). It doesn't contradict annotations, but doesn't enrich 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single, concise sentence that front-loads the action and object. No filler, and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, a read-only annotation, and a fully described input schema, the description is complete for this simple getter. It doesn't need to explain return values or parameters because structured fields cover those.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds no additional parameter meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Return' and identifies the exact resource ('the number of color correction nodes on a timeline item'). It clearly distinguishes from sibling tools like color_get_node_label or color_set_node_enabled by focusing on counting nodes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states the context ('on a timeline item') and the function is self-evident for counting nodes. It doesn't explicitly mention alternatives or exclusions, but for a simple getter this is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The destructiveHint annotation already flags this as destructive, so the description doesn't need to do so. It adds that deletion is by index, which indicates a precise removal rather than bulk, but doesn't disclose whether the action is irreversible or any additional side effects. This is acceptable given the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, immediately states verb and object. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a high-coverage schema, a destructiveHint annotation, and an output schema present, the description is sufficient for the agent to understand the operation. The only context (indices from gallery_get_stills) is captured in the parameter description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameter descriptions, including zero-based indices and album_name defaulting. The description itself adds no parameter details beyond the schema, so a baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states exactly what the tool does: deletes stills from a Gallery album using index-based targeting. This clearly distinguishes it from sibling tools like gallery_delete_album (deletes an album) and gallery_get_stills (retrieves stills).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that still indices should be obtained from gallery_get_stills, and the schema further clarifies that album_name defaults to the current album. However, it does not explicitly state when to use this tool versus alternatives or provide exclusion criteria, so it stops 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare destructiveHint=true, and the description confirms the destructive action while identifying the target. However, it does not disclose additional behavioral details such as permanence, failure modes, or effects on other takes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that includes the action, target, and scope. There is no redundant information or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the full schema coverage, destructive annotation, and existence of an output schema, the description is complete for a simple delete operation. It does not need to explain return values or prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage with detailed descriptions for all four parameters. The description adds no extra parameter semantics beyond what the schema already states (e.g., 'given index' mirrors the schema's '1-based index'), so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Delete a take at the given index on a timeline item.' It clearly distinguishes from sibling tools like item_get_take_by_index (read) and item_select_take_by_index (select).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: this tool is for deleting a take by index on a timeline item. No explicit alternatives or exclusions are mentioned, but the action is unambiguous enough to guide correct selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, and the description's 'Return' is consistent. It adds context about 'label color' but doesn't disclose return format, error cases, or other behavioral details. With annotations present, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler or redundancy. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only getter with full schema coverage and an output schema present, the description is complete enough. It identifies the purpose and domain without needing additional detail about return values or parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all three parameters (item_name, track_type, track_index) and defaults. The description adds no parameter-specific meaning, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Return') and identifies the resource ('label color assigned to a timeline item'), clearly distinguishing it from related tools like clip_get_color and item_set_color.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states it operates on 'a timeline item', providing clear context for when to use this tool among the many getter siblings. It doesn't explicitly name alternatives or exclusions, but the domain is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=true and the description's 'Return' are consistent. The description adds minimal behavioral context with 'currently set,' implying a read of current state, but does not discuss error cases, return format, or the influence of track parameters. With annotations covering safety, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that conveys the essential operation without unnecessary words. Every part of the description contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only getter, the description, combined with a complete input schema and an output schema, provides sufficient context. It specifies the operation and scope, while parameter defaults and return values are handled through the structured metadata.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all three parameters, including defaults for track_type and track_index. The description does not add any parameter-specific meaning beyond pointing at the target item, 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Return' and identifies the resource as 'all flag colors currently set on a timeline item.' This clearly distinguishes the tool from sibling clip_get_flags (which operates on media pool clips) and other item tools, making the operation and scope 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'timeline item' provides clear context that this tool is for items on a timeline, implicitly setting it apart from clip_get_flags for media pool clips. However, there is no explicit when-to-use or when-not-to-use guidance or named alternatives, so it does not reach the top score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint annotation, the description need not restate safety. It adds a behavioral nuance: the returned markers are keyed by frame offsets, which informs how to interpret output. Beyond this, no side effects, ordering, or edge cases are mentioned, but the annotation covers the critical read-only nature. Score 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences: the first states the purpose, the second adds a key detail about the return format. Every word earns its place, and it is front-loaded with the core action. No wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple read-only getter with well-documented parameters and an output schema. The description tells the agent exactly what it returns (all markers) and a key detail about the return structure (keys are frame offsets). With the annotations and schema, the description is sufficiently complete for correct use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all three parameters clearly described. The description provides no additional parameter context, but the baseline of 3 is warranted when the schema already fully documents the inputs. No extra value is added by the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Return all markers on a timeline item.' The verb 'Return' and resource 'markers on a timeline item' are specific, and the additional detail about keys being frame offsets distinguishes return format. It differentiates from sibling tools like clip_get_markers and timeline_get_markers by scoping to timeline items.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: for retrieving markers from a timeline item. It clearly establishes the resource type, which inherently guides selection among siblings (clip, timeline, item). However, it does not explicitly name alternatives or state exclusions, 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true, the safety profile is already covered. The description adds that the result is a collection of key-value pairs and that it includes all properties, which is useful behavioral context beyond the annotation. However, it does not mention edge cases like missing items or performance implications, which are not needed for a simple read.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that immediately conveys the resource (timeline item), the action (return all properties), and the output format (key-value pairs). No wasted words or redundant details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, read-only, and its output schema is present (as indicated by the context signals), so the description need not explain return values in depth. The description fully covers the purpose and result for this getter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents each parameter (item_name, track_type, track_index). The description adds no additional parameter-level explanation, so it does not enhance the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns all properties of a timeline item as key-value pairs. This distinguishes it from siblings that return specific properties (e.g., item_get_name, item_get_duration) and from clip_get_properties, which returns properties for clips rather than timeline items.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when all properties of a timeline item are needed, but it does not explicitly compare to alternatives or state when not to use it. No sibling tools are mentioned, so the agent must infer context from the wording.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation destructiveHint already signals destructiveness. The description adds the important scoping constraint ('current Media Pool folder' and 'by name'), which is useful. However, it doesn't disclose other behavioral traits such as irreversibility or effects on timeline references, though the annotation covers the key safety aspect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the action. Every word adds value and there is no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has one parameter, a destructive annotation, and an output schema. The description covers the essential purpose and scope, while the annotation covers the destructive nature and the output schema defines return values. This is sufficient for a simple deletion operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents clip_names as 'Names of clips to delete' (100% coverage). The description adds meaningful context by specifying these names are relative to the current Media Pool folder, which is not in the schema and helps the agent understand the execution scope.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (delete), target resource (clips), and scope (current Media Pool folder, by name). It distinguishes itself from sibling tools like media_pool_delete_folders and clip_delete_marker, so the agent can easily understand what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (delete clips from the current folder) but provides no explicit guidance on when to use this vs alternatives. It doesn't mention exclusions or alternative tools, so the agent has to infer from the name and sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=true already conveys the read-only nature, so the description doesn't need to repeat that. It adds context by specifying the exact scope ('currently selected Media Pool folder'), but it does not disclose additional behavioral details such as return format error conditions or edge cases. This is consistent with the annotations, so 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the verb and resource. Every word is necessary and there is no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and a clear output schema, the description is fully complete. It leaves no ambiguity about what the tool does or what it returns, and given the trivial nature of the operation, no additional context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the input schema is empty. The description adds no parameter-specific semantics, but with 0 parameters, the baseline is 4 per instructions. The description contributes by clarifying what the output refers to (the current folder's name).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('Get') and resource ('the name of the currently selected Media Pool folder'). It distinguishes from siblings like media_pool_get_root_folder and media_pool_set_current_folder by specifying 'currently selected'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (when you need the current folder name) but provides no explicit guidance on when to use this tool versus alternatives. It lacks exclusions or alternative tool references, which is a clear gap for the usage guidelines dimension.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only nature is known. The description adds value by specifying the return format ('A list of folder name strings') and the scope ('current database folder'), providing behavioral context beyond the annotation 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the purpose, and contains no redundant information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only list tool with an existing output schema, the description fully covers the essential behavior: what it lists and what it returns. No additional context is necessary for this simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so the baseline is 4. The description does not need to explain any parameter semantics, and it adds no misleading information. The return format is stated, which is the only relevant semantic detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and the resource 'sub-folders in the current database folder,' which is specific and distinct from sibling tools that open, create, or delete folders. The scope ('current database folder') differentiates it from other folder-listing tools like media_pool_get_subfolders or storage_get_subfolders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives. It does not mention how to navigate to a desired folder or that it only works on the current database folder, nor does it differentiate from sibling tools like project_folder_goto_root or storage_get_subfolders. The usage context is implied but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description consistently describes a read operation. However, the description adds no additional behavioral context beyond the annotation—no error conditions, prerequisites, or side effects are mentioned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single concise sentence, front-loaded with the verb, and contains no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
As a simple getter with no parameters, output schema present, and read-only annotation, the description fully covers the tool's purpose and scope. No additional context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description inherently provides all necessary semantic context. Baseline of 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Return' and resource 'start frame number of the current timeline', clearly distinguishing it from sibling timeline_get_end_frame.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states what data it retrieves but provides no explicit guidance on when to use it versus alternatives like timeline_get_end_frame. The 'current timeline' scoping implies context, but there are no exclusions or alternative references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should carry full behavioral disclosure. It clearly states that the operation is destructive ('replacing current'), which is a key behavioral trait. However, it does not explain whether the operation is reversible, what happens to the existing version data, or how remote versions (version_type=1) are handled, leaving some behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core action, and includes a useful contrast with a sibling tool. There is no unnecessary filler, making it concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's primary function and key differentiator, and the schema fully documents parameters. While it lacks detail on error conditions or version-type nuances, the combination of schema and brief description is adequate for the tool's complexity, though it could be more comprehensive given the lack of annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all 5 parameters, giving 100% schema coverage. The description itself does not add any parameter-specific information beyond what the schema already documents, so it neither enhances nor detracts from the schema's baseline clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific action 'Load' with a clear object 'a specific grade version onto a timeline item' and states the effect 'replacing current.' It also distinguishes this tool from set_current_version, making its purpose unambiguous relative to a sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly contrasts with set_current_version: 'Unlike set_current_version (which switches), load_version replaces the current grade data with the contents of the named version.' This tells the agent when to choose this tool over the alternative, providing clear usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavior. It explains the append-at-end behavior, the API method (AppendToTimeline), and the media type ('generator'), which adds value beyond the name. It does not mention error conditions or side effects, but the core behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the main purpose and followed by a useful implementation detail. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple one-parameter tool and the presence of an output schema, the description is reasonably complete. It states where the generator is inserted and how, but it doesn't explicitly note prerequisites (e.g., a timeline must be open) or what the return value indicates, though these are partially implied.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter, and the schema already includes a description with examples. The tool description adds no additional parameter semantics beyond what the schema provides, 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Insert a Fusion generator') and the target resource ('current timeline'), using the API AppendToTimeline with mediaType 'generator'. This clearly distinguishes it from sibling tools like fusion_insert_title, which handles titles.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: the tool appends the generator to the end of the current timeline. It does not explicitly mention alternatives or exclusions, but the phrasing implies it is for generators specifically, and the current-timeline requirement is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already declares a non-destructive operation. The description complements this by specifying the exact return unit (frames), confirming the read-only nature and adding useful behavioral detail beyond the annotation. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-structured sentence that immediately states the action and output. Every word earns its place; no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, has an output schema, and the description states the return value (duration in frames). However, it does not clarify which timeline is being referenced (e.g., current timeline), which could be ambiguous given the absence of a timeline parameter. Slight incompleteness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 no parameter-specific meaning beyond what the schema already provides (item_name, track_type, track_index). It references 'timeline item' but does not explain parameter roles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Return') and resource ('duration of a timeline item') with a clear unit ('frames'). It distinguishes itself from sibling tools like item_get_start_end and item_get_properties by focusing solely on duration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool: when you need the duration of a timeline item. However, it does not explicitly mention alternatives or exclusions (e.g., deriving duration from item_get_start_end), so it misses the top criteria but still provides clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden for behavioral disclosure. It explicitly states 'Only non-None parameters are applied; the rest remain unchanged,' which is a critical nuance preventing misinterpretation of null defaults as clearing values. This adds valuable transparency beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main purpose, and contains zero wasted words. It efficiently communicates both the action and the crucial merge behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple setter with 7 parameters and an output schema. The description covers the main action and important partial-update behavior. However, it doesn't specify value units or ranges for the crop numbers, which could lead to ambiguity, but this is a minor gap given the schema richness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds key semantics about how parameters behave: non-None values are applied, while null values leave the crop unchanged. This is not inferable from the schema alone and is essential for correct usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb and resource: 'Set crop values on a timeline item.' This distinguishes it from sibling tools like item_set_transform or item_set_composite, focusing specifically on crop adjustments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The tool implies usage when crop values need to be set, but it doesn't explicitly mention when to use it over alternatives or provide exclusions. The second sentence describes partial-update behavior rather than usage context, so guidance is limited.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only nature is disclosed. The description adds implementation context ('Runs ffmpeg's blackdetect filter') and intent, which provides value beyond the annotation. No contradictions exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise: two sentences with a clear front-loaded purpose statement followed by relevant context. Every sentence contributes value without redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple, and the output schema covers return values. The description covers purpose, use cases, and underlying implementation, which is sufficient for an agent to select and invoke the tool. Minor gaps like explicit file prerequisite are not critical given the obvious input definition.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 (file_path, threshold, min_duration_sec) with their defaults and meanings. The description adds no additional parameter semantics; it relies on the schema, which is acceptable at the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Detect black-frame spans') with a clear resource and scope (leader, slate gaps, missing media). It is easily distinguishable from siblings like media_detect_silence and media_probe, which focus on different detection tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear use cases ('locating a slate, 2-pop leader, or accidental black holes before conform'), indicating when to use the tool. It does not explicitly name alternatives or exclusions, but the context is sufficiently clear to guide appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It explicitly discloses the non-destructive nature ('The source is never modified') and the side-effect ('the frame is written to output_path'). This adds meaningful behavioral context beyond the schema, though it omits edge-case behavior like invalid timestamps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no filler. The first sentence states the core action, and the second adds valuable context about the intended downstream use. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a simple 3-parameter tool with a 100% covered schema and an output schema present, the description covers the essential purpose, safety property, and a use case. It could mention what happens if the timestamp is out of range or if the output format is unsupported, but those are minor gaps. Overall, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description does not add meaning beyond the schema — it references output_path and timestamp but the schema already provides equally clear descriptions (e.g., 'Seek position in seconds').
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource+scope: 'Extract a single frame at a timestamp to an image file.' This clearly distinguishes the tool from the sibling media_extract_frames (plural) by emphasizing 'single frame'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context for when to use the tool, noting that a vision-capable host can read the still 'to describe or QC the shot.' However, it does not explicitly name alternatives or state when not to use it, 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The destructiveHint annotation already warns about destructive behavior. The description adds valuable context by stating the project must not be open, implying the operation will fail or is unsafe otherwise. It also mentions 'irreversible' in the parameter description, which reinforces the permanent nature of the action beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loading the primary action and adding the critical precondition. No extraneous words or redundant information, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with one parameter and an output schema, the description covers the essential action and a key prerequisite. It does not detail failure modes (e.g., project not found) or return values, but the output schema is present to handle that. The tool's simplicity means this is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully covers the single parameter 'name' with a description ('Exact name of the project to delete. This action is irreversible.'), achieving 100% coverage. The main description repeats 'by name' but adds no additional semantic detail about the parameter format or behavior, 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Delete a project by name' with a specific verb (delete) and resource (project), clearly distinguishing from sibling operations like project_archive, project_save, or project_close. The scope ('by name') is explicit and matches the parameter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear prerequisite: 'The project must NOT be currently open.' This gives essential when-to-use context and implies the tool should not be used for open projects. However, it does not explicitly mention alternatives or list scenarios where a different tool would be preferred, such as using project_archive for non-destructive removal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral transparency burden. It discloses that clips are searched in the media pool's current folder and appended in order—behavior beyond the basic schema. It does not detail edge cases like missing clips, but the additive nature of the operation reduces the need for destructive warnings.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words: the first states the action, the second clarifies search and ordering behavior. The structure is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple one-parameter tool with an output schema. The description explains the core operation, search location, and ordering. It could mention what happens when no matching clips are found, but the description is largely complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes clip_names with 'List of clip names (as shown in the media pool)'. The description only reiterates that clips are matched by name, adding no new parameter-level detail. Baseline of 3 applies because schema coverage is 100%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Append') and clear resources ('media pool clips' to 'the end of the current timeline'), making the action unambiguous. It distinguishes itself from sibling tools like timeline_create_timeline_from_clips and timeline_delete_clips.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly states it appends to the current timeline, which is useful context for when to use this tool. It also explains the search scope (current folder), hinting at a prerequisite. However, it does not explicitly name alternatives or exclusion criteria, so it does not reach the top score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
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 reveals the method (speech-to-text), the output (subtitle track items), the version requirement, and the return value. It does not mention potential side effects like overwriting existing subtitles, failure behavior, or whether it is non-destructive, leaving some ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tightly written in three sentences plus a return value line. It front-loads the main action, includes only essential details (feature, requirement, return), and has no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless tool with an output schema, the description covers the action, method, version prerequisite, and return value. It is largely complete, though it could additionally mention failure behavior or side effects like duplicate subtitle track creation on repeated runs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema is empty with 100% coverage. Per calibration guidance, the baseline for 0 params is 4. The description adds context by specifying the input source ('audio in the current timeline') and the tool's mechanism, which is sufficient for the agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Auto-generate subtitles from audio in the current timeline.' It uses a specific verb ('generate'), identifies the resource ('subtitles from audio' in the timeline), and distinguishes itself from sibling tools like clip_transcribe_audio by explicitly mentioning it creates subtitle track items in the timeline.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by noting it uses Resolve's built-in speech-to-text and requires DaVinci Resolve 18.5 or later, which helps the agent understand when the tool is applicable. However, it does not explicitly list alternatives or state when not to use it, so it stops short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=true already tells the agent this is a safe, non-destructive operation. The description adds that the operation is scoped to a specific track and supports pagination, which is useful behavioral context. It does not mention ordering or behavior on empty tracks, but for a read-only list operation with an output schema present, the level of disclosure is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the core purpose and pagination capability without any filler or redundant information. Every word contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, a readOnlyHint annotation, and fully described parameters, the description is nearly complete for this simple list operation. It could mention the returned item structure or any notable behavior (e.g., order of items), but those are typically covered by the output schema. Overall, it provides sufficient context for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% description coverage for all four parameters, including defaults and meanings (limit, offset, track_type, track_index). The description adds little beyond what the schema states, so it does not significantly enhance parameter understanding. It correctly implies that 'specific track' relates to track_type and track_index but doesn't go beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' with a clear resource 'timeline items' and scope 'on a specific track', which distinguishes it from sibling tools like timeline_get_track_count or item_get_duration. It also mentions pagination, which is a key functional aspect not inferable from the name alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates when to use the tool: when you need to list items on a specific timeline track. It does not explicitly name alternatives or exclusions, but the context is clear enough given the focused scope and pagination note. A minor improvement would be to state that this is for browsing items rather than retrieving a single item.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds useful behavioral context beyond the readOnlyHint annotation, such as returning an empty list if the API is not supported or no groups are defined. This clarifies failure/edge-case behavior, which is valuable for the agent. It does not contradict the readOnlyHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core purpose. The extra return-format details are presented in a clear, structured block, with no redundant or filler text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple no-parameter read tool, the description is fully complete. It states the purpose, the return shape (list of dicts with name and id), and the empty-list fallback behavior, which is enough for an agent to use it correctly without needing an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters, the description has nothing to explain about parameters, and the baseline is 4. The description does add return format details, but that relates to output rather than parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List'), the resource ('color groups'), and the scope ('in the current project'). It is specific enough to distinguish from sibling tools like color_create_group and color_delete_group, which perform different operations on the same resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (when you need to see color groups in the current project) but does not explicitly mention alternatives or exclusions. There is no direct comparison to sibling tools like color_get_num_nodes or color_get_lut, so guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already indicates a safe read operation. The description adds important context by specifying the location (Resolve LUT directory) and the file pattern (*.dctl), which goes beyond the annotation. No contradictions exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that is both concise and complete. It contains no filler and directly conveys the tool's purpose and scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with zero parameters and an output schema, the description is fully adequate. It covers the purpose, scope, and location, and the readOnlyHint annotation handles safety information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes no parameters, so the description does not need to explain them. The baseline for zero parameters is 4, and the description adds no unnecessary parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('List') and resource ('installed DCTL files (*.dctl) in the Resolve LUT directory'). This distinguishes it from sibling tools like extension_list_fuses or extension_list_scripts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given about when to use this tool versus alternatives. However, the name and description make it clear that it is for listing DCTL files, implying usage when such a list is needed. Sibling tool names provide context but no direct comparison is offered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already declares this as a safe read operation. The description adds the scope of the directory but does not reveal traversal behavior, sorting, or return format details beyond what the output schema provides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
One clear, front-loaded sentence with no filler. Every word adds meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only list tool with an output schema, the description completely specifies the operation scope and purpose. No additional context is required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is nothing to document. The schema coverage is vacuously 100%, and the baseline for no parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') with a clear resource ('installed Fuse files') and location ('Fusion Fuses directory'). It distinguishes from sibling tools like extension_list_dctl and extension_list_scripts by the file type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the use case clear (enumerating installed fuses) but does not explicitly name alternatives or exclusion scenarios. Its specificity is enough to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true in annotations, the safety profile is already known. The description adds the open-project requirement and specifies that it returns all album names as strings, which is useful behavioral context beyond the annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with the primary action front-loaded. Both sentences add value: the first states what the tool does, the second clarifies output format and a prerequisite. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple parameterless read-only listing tool. The description covers purpose, output, and a prerequisite. Since an output schema exists, return values do not need detailed explanation. The description is 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.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description does not need to explain parameter meanings. The baseline for 0 parameters is 4, and the description adds relevant output context without being redundant.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('still albums in the Gallery'), clearly distinguishing it from sibling tools like gallery_get_stills or gallery_create_album. The added sentence 'Returns album names as strings' further specifies the output type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states a prerequisite ('Requires an open project'), which gives some usage context. However, it does not explicitly mention when to use this tool versus alternatives such as gallery_get_current_album or gallery_get_powergrade_albums, so guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given the readOnlyHint annotation, the description adds useful behavioral context by specifying that an empty string is returned when no album is selected. This edge-case disclosure goes beyond the annotation and clarifies expected return 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the primary purpose and immediately adding the edge-case behavior. No extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with no parameters and an output schema. The description explains the return value and its edge case, which is sufficient for agents to invoke and interpret the result correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters, the input schema fully covers parameter semantics. The description does not need to elaborate on parameters, and the baseline of 4 for no-parameter tools is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the name of the currently active still album, using a specific verb and resource. It is easily distinguished from sibling tools like gallery_get_albums (which lists all albums) and gallery_set_current_album (which changes the current album).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for querying the current album state but does not explicitly state when to use this tool versus alternatives. No exclusions or alternative tool recommendations are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=true already covers the read-only nature. The description adds value by disclosing that the source may not be available, implying possible null/empty behavior. This is a useful behavioral nuance beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence that is front-loaded with the key action and resource. No redundant words; every segment earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only lookup with a full output schema and 100% parameter coverage, the description provides the essential context. It explains what the tool returns and the conditional nature, which is sufficient for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are fully defined in the schema. The description adds no parameter-specific guidance. Baseline of 3 applies since the schema carries the semantic load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Return') and resource ('source media-pool clip for a timeline item'), clearly distinguishing this from other item_* getters (like item_get_name) and media_pool_* tools. The conditional 'if available' adds scoping.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use: when you have a timeline item and need its originating media-pool clip. However, it doesn't explicitly contrast with alternatives or state exclusions (e.g., 'use this instead of media_pool_get_clips for timeline items'). Context is clear but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=true already signals a safe read operation. The description adds meaningful behavioral context by noting the ID is stable across project saves, a non-obvious property that is not inferable from the annotation 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action and followed by the key behavioral detail. Every word contributes value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple read-only operation with a complete input schema, read-only annotation, and an output schema. The description sufficiently covers the essential context—what it returns and why the ID is useful—making it complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all parameters with descriptions, so the description need not repeat them. It does add the conceptual context that the item is a timeline item, but no additional parameter-level semantics are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Return' and the resource ('unique identifier for a timeline item'). It distinguishes itself from sibling item tools by emphasizing the stable, programmatic reference use case, which is unique among item_get_* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does 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: when a stable ID is needed to reference a specific item programmatically. It does not mention alternatives or exclusions, but the context is sufficient for most use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already signals safety. The description adds behavioral context: 'current Media Pool folder' and 'pagination', which are important for the agent to know it must be in the right folder and can page through results. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence of 10 words that is front-loaded with the action and resource, and efficiently communicates the only two additional pieces of context (current folder, pagination). No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list operation, the description covers the essential context: what is listed (clips), where (current Media Pool folder), and how (pagination). Annotations declare safety, the output schema documents return values, and the parameter schema fully explains pagination controls, so nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers both parameters (limit and offset) with detailed descriptions and defaults, achieving 100% schema description coverage. The description only mentions 'pagination' generically, adding no extra meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('clips'), and clearly scopes to 'current Media Pool folder' with pagination. This distinguishes it from sibling tools like media_pool_get_subfolders or clip_get_name, which operate on different resources or aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: this tool lists clips in the current Media Pool folder, with pagination. It implicitly indicates when to use it (when you need clips in the current folder) and does not conflict with alternatives, but it does not explicitly name alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=true already establishes the safety profile, and the description adds a useful domain fact ('Every project has exactly one root folder, usually named Master'). Beyond that, there is no detail on error behavior or what happens when no project is open, but for a simple getter this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, first states purpose directly, second adds a relevant detail about the root folder's uniqueness and typical name. No filler or repetition. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's extreme simplicity (no input parameters), the annotations provide the safety profile, and an output schema exists to describe return values, the description covers everything needed. It clearly identifies the tool among many media pool siblings and provides just enough domain context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description doesn't need to elaborate on parameter semantics, as there are none. The mention of 'name' as the return value gives a hint about the output, but parameter-wise there is nothing to document.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: to get the name of the Media Pool's root folder. It uses a specific verb ('Get') and resource, and the added note about the root folder being unique distinguishes it from sibling tools like media_pool_get_current_folder or media_pool_get_subfolders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: whenever the name of the root folder is needed. The statement 'Every project has exactly one root folder' provides useful context, but there is no explicit exclusion or mention of alternatives. However, the tool's purpose is so specific that context alone is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation covers safety, and the description adds that it returns names only and all subfolders, which is useful behavioral context beyond the annotation. It does not mention recursion or edge cases, but given annotation coverage, this 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, clear, and well-structured with the action first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple zero-parameter read-only tool with an output schema, the description fully covers what an agent needs to know to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so the description does not need to explain them. The schema is empty and the tool has no input requirements.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists subfolder names within the current Media Pool folder, using a specific verb and resource. It distinguishes from sibling tools like media_pool_get_current_folder or media_pool_get_clips.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit when-to-use or alternatives, but the operation is self-evident. It is implied you would use this to enumerate subfolders in the current folder, but no exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=true already signals this is a read-only operation. The description adds value by enumerating all possible return values (pages) and the edge case where an empty string is returned if Resolve cannot determine the page. This provides useful behavioral detail beyond the structured annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a single leading sentence stating the purpose, followed by a compact list of possible return values. Every sentence earns its place, with no redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only getter, the description is complete. It fully specifies the return values, including an edge case, and given the existence of an output schema (as indicated by context signals), the description does not need to explain return structure further. The tool's simplicity means no additional context is required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline for this dimension is 4. The description adds no parameter information because none exists, and none is needed. The description focuses on output semantics, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Return' and a clear resource ('the name of the currently active Resolve page'). It is easily distinguished from sibling tools like playback_open_page, which implies setting or navigating to a page.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes it clear this is a getter for the active page, but does not explicitly state when to use it versus alternatives such as playback_open_page. Usage is implied by the tool name and the list of possible return values, but no explicit 'when to use' or exclusionary guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds context beyond that by specifying the prerequisite of an open project with a timeline and giving an output example. It does not cover error behaviors or edge cases, but the safety profile is already established by the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first states the purpose with an example, the second states the prerequisite. Every word is useful and front-loaded; there is zero waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema is present, so return structure is already documented. For a parameterless, read-only tool, the description covers purpose, output format, and prerequisites, making it complete enough for an agent to decide when and how to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the input schema is empty, so there are no parameter semantics to document. Baseline for no parameters is 4, and the description does not need to add parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the current playhead timecode with a concrete example format, making the action and resource unambiguous. It distinguishes itself from siblings like playback_set_timecode and playback_get_current_item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear precondition for use ('Requires an open project with at least one timeline'), which guides the agent on when the tool is appropriate. It does not mention explicit exclusions or alternatives, but the context is sufficient for a simple read-only operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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 the key behavioral traits: the operation saves automatically before closing, and it returns True only on successful closure. This addresses potential concerns about data loss and success indication, which is strong for a simple close operation. It could have mentioned failure behavior, but the return value handles that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence for the action and one for the return value. Every word earns its place, and the format is clean and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters, an output schema indicating boolean return, and a simple close operation, the description fully explains what happens (closes and saves) and what the return value means. There is no missing information that an agent would need to select or invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema is empty. Per the baseline for 0 params, the description need not add parameter semantics. It is complete and accurate in stating no inputs are required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description precisely states the action: 'Close the current project' with the specific verb 'close' and resource 'current project'. It also adds a key behavioral detail ('saves automatically before closing') that distinguishes it from related tools like project_save or project_delete, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when you want to close the current project), but it does not explicitly mention alternatives or exclusions. Sibling tools like project_save and project_delete exist, but the description does not state 'use project_save to save without closing' or similar guidance. Usage context is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The destructiveHint annotation already signals danger, and the description adds the key behavioral constraint that the folder must be empty. This goes beyond what annotations alone convey, making the tool's behavior more transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loaded with the action and resource, and every word adds value. No unnecessary details or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple deletion tool with one fully documented parameter, the description completely covers what an agent needs to know: what it does, where it operates, and a critical precondition. The output schema exists, so return values need not be described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema coverage at 100% and the parameter description 'Name of the folder to delete' being clear, the tool description adds only the context of 'current database folder' which is already in the description. This meets the baseline for high coverage without adding significant extra meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb 'Delete' and clearly identifies the resource: a folder in the current database folder. This distinguishes it from sibling tools like project_folder_create or project_folder_list, and the scope ('current database folder') is explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear prerequisite: the folder must be empty. This is essential usage guidance, though it does not explicitly mention alternatives or when not to use the tool. Still, the context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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 core behavior (moving up one level) and the return values (True/False, including the edge case of already being at root). This is sufficient for a simple navigation tool, though it does not detail side effects or error conditions beyond the boolean return.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: one for the action and one for the return values. Every word is useful, and it is front-loaded with the primary purpose. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter navigation tool with an output schema, the description fully covers what it does and what to expect in return. It includes the important edge case of being at the root, which is essential for correct invocation and interpretation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema is empty, so the baseline is 4. The description correctly notes the behavior and return values without needing any parameter documentation, as there are none.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Navigate up one level in the project database folder hierarchy.' It clearly distinguishes from siblings like project_folder_goto_root, which goes to the root rather than just one level up.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool (when needing to move to the parent folder), but it does not explicitly mention alternatives or exclusions, such as 'use project_folder_goto_root for root.' It leaves the when-not-to-use to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already indicates the operation is read-only. The description adds useful context about the return structure, including the optional 'IpAddress' key for remote databases, which helps the agent understand what to expect. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences with clear front-loading of the main action followed by return details. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with no parameters and a clear return format in the description, the information is complete. The agent can invoke it without ambiguity. The output schema presence further reduces the burden on the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so schema coverage is 100% by default. The description doesn't need to explain parameters; it appropriately focuses on the return value. Baseline for 0 params is 4, which is justified here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'List all available project databases' with a specific resource and scope. It distinguishes from sibling tools like project_get_database (singular) by indicating this lists all databases, not just the current one. The return format is also specified.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: when you need to list databases. However, it does not explicitly mention when NOT to use this tool or provide alternatives. Sibling tools like project_get_database exist but are not referenced. The context suggests this is the tool for listing databases, but no explicit guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/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 that results are alphabetically ordered and returned as a list of strings. It does not cover edge cases like empty folders or errors, but for a simple listing tool this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loading the main action and then specifying the return format. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only tool with an output schema, the description fully explains what the tool does and what it returns. It lacks nothing essential for an AI agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the input schema is trivially complete. The description adds meaning by specifying the output is an alphabetically-ordered list of project name strings, which provides context beyond the empty parameter list.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all project names in the current database folder, using a specific verb ('List') and resource ('project names'). It also specifies the return format (alphabetically-ordered strings), distinguishing it from sibling project management tools like project_create or project_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for retrieving project names when needed, and there is no sibling tool that lists project names (project_folder_list lists folders). However, it does not explicitly state when to use it versus alternatives or include any exclusions, so it stops short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already declares this as a safe read operation. The description adds the return format and 'currently selected' state, but does not disclose error conditions, dependencies on prior settings, or any other behavioral traits. It is adequate but not substantial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose, followed by a precise return description. Every word earns its place; there is no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only getter with an output schema, the description fully captures the tool's purpose and return type. The sibling set introduces no ambiguity, and the description is sufficient for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so the description does not need to explain them. The baseline of 4 applies; the description correctly avoids inventing any parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Return' and identifies the exact resource 'currently selected render format and codec', clearly distinguishing it from siblings like render_get_formats and render_get_codecs which list available options. This is precise and 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'currently selected' provides clear context that this tool queries the current render output state, implying when to use it. However, it does not explicitly mention alternatives or when not to use, so it stops 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already include readOnlyHint=true, so the read-only nature is covered. The description adds that all jobs in the queue are returned and includes a return format, but with an output schema present, this adds limited value beyond the annotation. No extra details like pagination or edge cases are provided, consistent with a simple read-only list tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two sentences that state the action and the return shape. Every word earns its place, with no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only list tool with an output schema, the description fully covers purpose and scope. It gives the return structure and the queue context, which is sufficient for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline of 4 applies. The description properly avoids unnecessary parameter explanation since there is nothing to document.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns all render jobs in the queue with their current status. It uses a specific verb ('Return') and resource ('render jobs in the queue'), distinguishing it from sibling render tools like render_get_status or render_add_job.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this tool lists queued render jobs, but it does not explicitly mention when to use it over alternatives such as render_get_status. No exclusions are given, so it earns a 4 rather than a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond the readOnlyHint annotation by disclosing that the underlying API may return a list or string, and that this tool normalizes to a single joined string. This helps an agent understand potential format inconsistencies and the tool's guarantee. It does not describe error cases or other edge behaviors, but for a simple getter this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, directly front-loaded with the core purpose, followed by a necessary clarification about the return type. Every sentence earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only getter, the description fully explains what is returned and the normalization behavior. The output schema likely documents the return type, and the description complements it well. No additional context is needed for an agent to invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters, the description has no parameter burden. The baseline of 4 applies because there is nothing to document, and the description correctly focuses on the return value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the DaVinci Resolve version as a dotted string, with a concrete example. This differentiates it from the sibling tool resolve_get_product, which presumably returns product name or type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus alternatives like resolve_get_product. However, the tool's purpose is self-evident, and it is implied that this is the go-to for the version string. No exclusions or alternate use cases are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description is consistent with a read-only operation. The description adds no further behavioral details (e.g., behavior when no timeline is open, inclusivity of frame numbers), but the annotation reduces the burden. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no unnecessary words. It is front-loaded with the verb and immediately states the result. Perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, has no parameters, and an output schema exists to document the return type. The description fully explains what the tool does. There are no missing pieces for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema provides full coverage (100%). No parameter semantics are needed, and the description does not add any. Baseline for 0 parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action (return), the resource (end frame number), and the scope (current timeline). It distinguishes itself from sibling tools like timeline_get_start_frame and timeline_get_current by naming the exact data returned.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: use this tool to get the end frame number of the currently active timeline. It does not explicitly mention alternatives or exclusions, but the purpose is unambiguous enough that an agent can decide when to call it. A 5 would require explicit when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=true already indicates a safe read operation, and the description adds useful behavioral context by disclosing the error condition when no timeline is open. This goes beyond the annotation without contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loaded with the primary action and supplemented by a concise error note. Every word earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple getter with no parameters and an output schema present, the description fully covers the tool's purpose and the key precondition (open timeline). No additional context is needed given the low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema coverage is trivially 100%. The description does not need to explain parameters, and with 0 params the baseline is 4, which is appropriate here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Return the name of the current timeline,' using a specific verb and resource. This clearly distinguishes it from sibling tools like timeline_set_name (which sets) and timeline_get_current (which returns the timeline object, not its name).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by noting 'Raises an error if no timeline is open,' which informs the agent when the tool is applicable. However, it does not explicitly compare to alternatives or provide when-to-use guidance beyond this error condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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 captures a snapshot, adds it to the current album, returns True on success, and may require the Color page with a valid viewer image. This addresses action and failure conditions, though it does not delve into other side effects or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded and efficient at four sentences. However, the first sentence ('Grab a still from the current viewer into the current album') is largely redundant with the second sentence ('Captures a snapshot ... and adds it to the current still album'), so it is not perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple no-parameter tool with an output schema, the description is complete: it explains what the tool does, how it works, what it returns, and a key prerequisite. The sibling gallery tools provide additional context, and nothing important is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and an empty input schema. The description correctly includes no parameter details, matching the baseline 4 for 0-param tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Grab a still from the current viewer into the current album.' It clearly distinguishes this tool from siblings like gallery_get_stills (listing) and gallery_import_stills (importing) by specifying source (viewer) and destination (current album), and references the Color page 'Grab Still' button.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: it captures the current viewer display and adds it to the current still album, equivalent to the 'Grab Still' button. It also states the prerequisite of being on the Color page with a valid viewer image. It does not explicitly name alternatives or exclusions, but context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full behavioral disclosure burden. It successfully reveals the partial-update semantics (null parameters are ignored, existing values preserved), which is key behavioral context beyond the schema. It does not discuss error cases or permissions, but for a setter tool this is a meaningful and sufficient disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, with the main action in the first sentence and the crucial qualifier in the second. Every word adds information, and the structure is front-loaded with the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 10-parameter schema and no annotations, the description plus schema covers the action, parameter meanings, and update behavior. However, the role of track_type and track_index in identifying the target item is not explained, which is a small but relevant gap. Since an output schema exists, not describing return values is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does 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 valuable parameter-level semantics by explicitly stating that only non-None parameters are applied, clarifying that null means 'leave unchanged' rather than 'clear the value.' It also groups the main transform parameters, reinforcing what they collectively affect.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb with a clear resource and property list: 'Set transform properties (zoom, position, rotation, anchor) on an item.' This directly distinguishes it from sibling tools like item_set_property, item_set_crop, or item_set_composite.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage guidance by stating 'Only non-None parameters are applied; the rest remain unchanged,' which tells the agent how to use optional parameters. It implies this tool is for transform updates, but it does not explicitly list when not to use it or name alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, and the description reinforces this with 'Return'. It adds behavioral context by explaining the expected output values (DaVinci Resolve vs DaVinci Resolve Studio), which is useful beyond the annotation. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two brief sentences, with the core action in the first. No filler or redundant details. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and an output schema exists, the description provides sufficient clarity about the return value. It includes typical values, which helps set expectations. It could add error conditions, but the simplicity makes this complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the description's job is not to explain inputs. It instead clarifies the output semantics, which is the next best thing. The baseline of 4 for zero-parameter tools is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Return' and specifies the resource 'Resolve product name'. It distinguishes this from sibling tools like resolve_get_version by clarifying that it returns the edition (free vs Studio), not the version.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: when you need the product name/edition. It does not explicitly name alternatives, but brother tools like resolve_get_version make the differentiation clear. The stated typical values (free vs paid) provide practical context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description adds the exact neutral CDL values (Slope, Offset, Power, Saturation) and clarifies that nodes are not removed. This gives the agent crucial behavioral insight about what the operation actually changes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the primary action, then relevant details. No filler. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with only three parameters and an output schema. The description fully explains the effect, the target, and the key nuance (nodes preserved). Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the input schema already documents all parameters. The description mentions 'timeline item' which maps to item_name, but adds little beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool resets a timeline item's grade to identity CDL values, which is a specific verb+resource combination. It distinguishes itself from siblings like color_set_cdl by focusing on the reset-to-neutral 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it: to neutralize a grade without removing nodes. It provides clear context for the operation but does not explicitly mention alternatives or when not to use it, 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint: true, and the description adds valuable context about environment overrides ('RESOLVE_*_DIR') and the fact that directories may not exist yet, noting a write creates them. This goes beyond the annotation without contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the core purpose, followed by two relevant details. Every sentence earns its place with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless read-only tool with an output schema present, the description covers the use case, environment variable behavior, and directory existence semantics. It is complete and leaves no significant gaps for an agent to invoke and interpret results correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema is empty. The description adds meaning by explaining what the returned directories represent, but since there are no parameters, the baseline of 4 applies as no parameter details are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Return' and the specific resource 'resolved on-disk directories for each extension type.' It distinguishes from sibling tools that list, write, read, or remove specific extension files, while this tool focuses solely on path resolution.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the tool is useful for confirming where DCTLs, Fuses, and Scripts will be written, providing clear context for when to use it. It does not explicitly mention alternatives or when-not-to-use scenarios, but the context is sufficient given the tool's narrow purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the responsibility for behavioral disclosure. It reveals that the clip is appended via AppendToTimeline, that audio-track targeting is limited, and that it operates on the current timeline. This is transparent about the main behavioral nuances, though it doesn't cover edge cases like missing timeline or failure 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the first sentence states the purpose, the second provides mechanism and a caveat. Every sentence earns its place with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity, the complete input schema, and the presence of an output schema, the description covers all essential aspects: what it does, where it operates, the import step, and the track targeting limitation. It is sufficiently complete for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds context beyond the schema by explaining the two-step process (import then append) and reinforcing the track_index limitation. This adds meaningful value, especially for understanding how the parameters fit into the overall operation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool imports an audio file and inserts (appends) it to an audio track on the timeline. This is a specific verb+resource combination that distinguishes it from related tools like media_pool_import_media (which only imports to the Media Pool) and timeline_append_clips (which appends existing clips).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the full workflow (import to Media Pool, then append to current timeline) and notes a key limitation about audio-track targeting. However, it does not explicitly name alternative tools or provide clear when-to-use vs when-not-to-use guidance, leaving some usage context implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With the readOnlyHint annotation already covering the read-only nature, the description adds meaningful context: the persistence of grades across projects and the caveat about availability in all Resolve versions. These are behavioral traits beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences: the first states the primary action, the second gives domain context, and the third provides an important caveat. Every sentence earns its place without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple parameterless read-only tool with an output schema, the description is complete. It covers purpose, domain meaning, and availability, which is sufficient for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description need not explain any. The baseline for 0 params is 4, and the description adds no parameter-specific info, which is acceptable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'List the names of all PowerGrade albums in the Gallery,' using a specific verb and resource. It clearly distinguishes from sibling tools like gallery_get_albums by specifying 'PowerGrade albums', which is a distinct category.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context about PowerGrade albums ('contain grades that persist across projects') and warns about version availability. However, it does not explicitly compare with alternatives like gallery_get_albums or state when not to use it, 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses the return type (dict with keys name, start, end, duration) and the edge case (returns None when no item or no open timeline). This gives the agent concrete behavioral expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences deliver the purpose and return details without waste. The first sentence front-loads the action, and the second adds the return shape and edge-case behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless, read-only tool, the description fully explains what it returns (dict with four keys), the None condition, and the absence of parameters. The context signals confirm simplicity, and nothing is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the empty input schema fully covers parameter semantics. The description adds no parameter information because none is needed; baseline 4 applies for parameterless tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Return info about the timeline item under the playhead', clearly identifying the action (return info) and specific resource (timeline item under playhead). This distinguishes it from siblings like playback_get_timecode or item_get_name, which target different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use: to get info about the current timeline item. It also notes the None condition when no item is under the playhead or no timeline is open. No explicit alternatives are named, but the scope is well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already indicates a safe read operation. The description adds value by specifying the exact return shape (name and timeline_count), which is useful behavioral context not provided by 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the purpose, and includes only essential return type details. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple no-parameter read operation with an output schema. The description fully covers the return keys, and given the low complexity, there are no significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters. The description adds meaning by clarifying the return structure, which is helpful even though the schema is empty. Baseline 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb 'Return' with the resource 'currently open project' and explicitly lists the returned keys. This clearly distinguishes it from sibling project tools like project_get_setting or project_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies use when you need basic info about the current project, but it does not explicitly mention alternatives or exclusions. For a simple no-parameter getter, this context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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 the precondition, the action of queueing, and the return value (job ID). It does not explicitly state that the job does not start automatically, but the separate render_start sibling and the concept of a queue make this implicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, action first, includes return type. No wasted words. The front-loaded verb and resource make it immediately scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no params, output schema present), the description covers prerequisites, action, and result. It is sufficient for an agent to know when and how to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the schema requires no explanation. The description correctly references 'current settings' without needing to enumerate them, and the baseline for no params is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Add' and identifies the resource: 'current timeline to the render queue with current settings'. This clearly distinguishes it from sibling render tools like render_start (which starts rendering) or render_delete_job (which deletes jobs).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It states prerequisites: 'The timeline must be set (Deliver page) and render settings must be configured before calling this tool.' This gives clear context for when to use it. It does not explicitly name alternatives, but the precondition implies sequencing relative to configuration tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true annotation, the safety profile is already disclosed. The description adds value beyond annotations by specifying the exact return structure (a map of formatName to description) and indicating that the format names are usable as inputs to other tools. This gives behavioral context about the output's semantics without contradicting the read-only 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is optimally concise: two sentences, front-loaded with the core purpose, followed by a practical usage note. No filler or redundancy, every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and an existing output schema, the description covers the essential context: what it returns and how the result feeds into sibling tools. The presence of the output schema means detailed return-field documentation is not required in the description. It is fully complete for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so per rubric the baseline is 4. The description correctly implies that no parameters are needed, and there is no additional parameter information required to invoke the tool correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Return available render formats as {formatName: description}.' It uses a specific verb ('Return') and resource ('render formats'), and distinguishes itself from sibling tools like render_get_codecs and render_get_presets by focusing on formats rather than codecs or presets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides direct usage guidance: 'Use the format names as input for render_get_codecs() or render_set_format_and_codec().' This tells the agent when to use this tool (to obtain format names for downstream render operations) and connects it to relevant siblings. It stops short of explicitly listing when not to use it, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, so the safety profile is known. The description adds the return format ('a list of preset name strings') and the fact that it lists 'all' presets without filtering, providing useful behavioral context beyond 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action and resource. The second sentence adds return details and usage, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple tool with no parameters, an output schema, and readOnly annotation. The description fully covers what it does, returns, and how to use the result. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters and schema coverage is 100%, so no parameter explanation is needed. The description's 'List all' clarifies there are no required inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all saved render preset names' with a specific verb and resource. It distinguishes this tool from siblings like render_get_formats and render_get_codecs by specifying 'preset names'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by noting the returned names can be passed to render_load_preset(). This provides clear context on when to use the tool, though it doesn't explicitly exclude alternatives or state when-not-to-use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the key behavioral trait: the tool is idempotent and returns True whether or not a render was actually running. It does not mention side effects or edge cases, but for a simple stop operation, this level of disclosure is adequate and adds value beyond a basic statement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and efficient, consisting of only two short sentences. It front-loads the action and then adds the important return behavior without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless tool with an output schema present, the description is fully complete. It explains the tool's purpose and return behavior (including idempotency), which is all the agent needs to invoke it correctly and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema fully covers parameter semantics. The baseline for 0 params is 4, and the description correctly does not include any parameter information since there are none.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Stop the currently running render.' It uses a specific verb and resource, and the name 'render_stop' aligns perfectly with the described behavior. It is distinct from sibling tools like render_start and render_get_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does 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 you want to stop a running render and the idempotency ensures it is safe to call even if no render is in progress). It does not explicitly name alternatives or exclusion criteria, but the context is sufficient given the simple nature of the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds useful behavioral context: it returns volume paths with platform-specific examples, and specifies the source of these volumes (Media page's storage panel). This informs the agent about the nature of the return data beyond just 'read only'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action, and immediately provides concrete examples of return values. Every word contributes value without redundancy, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with no parameters, the description fully covers what the tool does, what it returns, and where the data comes from. The output schema (though not shown) is implied to list paths, and the description aligns with that expectation. No additional context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description correctly provides no parameter details. The baseline of 4 applies because there is no parameter complexity to explain, and the focused text covers the tool's behavior sufficiently.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('List') and resource ('mounted media storage volumes visible to DaVinci Resolve'), and distinguishes it from sibling tools like storage_get_subfolders and storage_get_files by focusing on top-level volumes. The examples of volume paths further clarify the resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool: to retrieve all mounted media volumes that appear in the Media page's storage panel. It does not explicitly mention alternatives or exclusions, but the scope is well-defined and differentiates it from storage navigation tools that operate at subfolder/file levels.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description's 'Analyzes the video content and returns frame numbers' is consistent with a read operation. It adds useful context beyond annotations, such as requiring Resolve 18.5+ and targeting the current timeline. No contradiction is present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded, with three short paragraphs. Each sentence adds value: the first gives the core action, the second explains the process, the third states a requirement, and the last describes the return. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, a read-only annotation, and an output schema, the description is complete. It covers purpose, scope, a version prerequisite, and return type. No additional behavioral complexities need explanation for a tool of this simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. There is nothing to explain about parameters; the description's mention of 'current timeline' as a scope, not a parameter, is adequate. Schema coverage is 100% by having no properties.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Detect scene cuts in the current timeline.' It clearly distinguishes itself from sibling tools by focusing on the current timeline and mentions that it analyzes video content and returns frame numbers, which is a clear and unique 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states it operates on the current timeline, which contextualizes when to use it. It also includes a version requirement ('Requires DaVinci Resolve 18.5 or later'), which is a prerequisite. However, it does not explicitly mention alternatives or when not to use it, so it lacks explicit exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, and the description adds valuable behavioral detail: the return format is a dict mapping frame numbers to marker info dicts with specific fields, and it explicitly handles the no-markers/no-timeline edge case by returning an empty dict. This is transparent and goes beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-sentence purpose, followed by a clear return-value summary with fields and an edge-case note. Every sentence adds value, and there is no wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, parameterless read-only tool, the description is complete. It explains what is returned, the structure of the returned markers, and the behavior in edge cases (no markers or no open timeline). The existing output schema and readOnly annotation further reduce the need for additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters and the schema description coverage is 100%, so there is nothing for the description to clarify about parameter semantics. The baseline of 4 is appropriate because the description has no parameter burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Return all markers on the current timeline,' which uses a specific verb ('return') and clearly identifies the resource (markers on the current timeline). This distinguishes it from sibling tools such as clip_get_markers and item_get_markers, which operate on different scopes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states the tool reads markers from the current timeline, and it notes that an empty dict is returned if no timeline is open. It does not explicitly name alternatives like clip_get_markers or item_get_markers, but the scoping to 'current timeline' provides clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses honest limitations: 'reports its structure honestly rather than pretending to fully decode it,' then enumerates exactly what is extracted (root tag, child tags with counts, approximate node count, ASC CDL SOP values). This gives the agent a realistic expectation of output fidelity and scope.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two short paragraphs: the first states purpose, the second adds essential behavioral detail and the application alternative. Every sentence provides distinct value, no filler, and the most important info is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only inspection tool with an output schema, the description sufficiently covers what the tool does, its limitations, and sibling alternatives. It addresses the complexity of the proprietary .drx format without over-explaining, and the output schema handles return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers the single parameter (file_path) with a clear description ('Absolute path to a .drx file'), so the description adds no extra parameter semantics. With 100% schema coverage, the baseline of 3 applies; the description does not need to compensate further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource+scope: 'Inspect a Resolve .drx grade-exchange file (read-only).' It clearly distinguishes this from sibling tools like color_apply_drx by focusing on inspection rather than application, and explicitly names the file type being handled.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says to use other tools for applying the .drx: 'Apply a .drx inside a running Resolve with the timeline / timeline_item grade tools (ApplyGradeFromDRX).' This provides a clear when-not-to-use directive and names alternatives, making usage context unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses the return type (strings) and the empty-list behavior when the API is unavailable. This adds meaningful behavioral context beyond the annotation, so it gets full credit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main purpose, and includes the return type and edge case without redundancy. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with an output schema, the description is complete: it states what it lists, what it returns, and the edge case. The version caveat adds important context for the user. No significant gaps are present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description adds value by specifying the output format, which indirectly clarifies what the tool does with its (nonexistent) parameters. No compensation is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List') and a specific resource ('Fairlight audio effect presets'), with additional detail about return format (strings) and an edge case (empty list). This clearly distinguishes it from siblings like fairlight_apply_preset or fairlight_insert_audio.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context (listing presets vs applying them) and notes version-dependent availability, but does not explicitly mention alternative tools or when not to use it. This is a minor gap, so it earns a 4 rather than a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description adds valuable behavioral details: it returns None when no timeline is open, and it specifies the exact dictionary keys (name, start_frame, end_frame, video_tracks, audio_tracks, start_timecode). This goes beyond what annotations provide and sets clear expectations for the return value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence for purpose and one for return structure. It is front-loaded with the most important information and contains no filler or redundant text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with no parameters and a provided output schema, the description is fully complete. It explains the primary behavior, the edge case (None), and the return structure, leaving no significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, and the empty schema covers all cases (100% coverage). The 0-parameter baseline is 4, and the description correctly avoids adding unnecessary parameter details since there are none to describe.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns info about the current timeline, with a specific verb ('Return info') and resource ('current timeline'). It also distinguishes from sibling tools like timeline_get_by_index or timeline_get_name by focusing on 'current' and listing the full set of returned keys.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (when you need the current timeline's info) by using the word 'current,' which differentiates it from timeline_get_by_index and timeline_get_count. However, it does not explicitly mention alternatives or provide exclusion criteria, 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.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/luquimbo/davinci-resolve-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server