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

With no annotations provided, the description carries the full burden. It does disclose that this is a read operation, implying a non-destructive action, but it does not explain identifier precedence, behavior when no parameters are supplied, or error handling. This is minimally transparent but lacks depth.

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

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

The description is a single concise sentence with the core purpose front-loaded and no filler. However, the brevity comes at the cost of omitting essential parameter and usage details, making it efficient but incomplete.

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

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

Although an output schema exists, the description is insufficient on its own because it does not explain how to select a clip via the three optional parameters. With no annotations and no parameter guidance, an agent lacks enough context to call the tool confidently.

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

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

Schema description coverage is 0%, and the description does not mention path, media_id, or clip_name at all. It provides no guidance on how to identify the clip or whether at least one of these optional parameters is required, so it adds no semantic value beyond the schema.

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

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

The description uses a specific verb, 'Read', and clearly identifies the resource: metadata for a media pool clip. The phrase 'built-in and third-party metadata' helps differentiate it from sibling tools like markers_query and clip_set_color, though no alternative tool is explicitly named.

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

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

There is no guidance about when to use this tool versus alternatives such as markers_query, inspect, or type_registry_get. The description only states what the tool does, leaving the agent to infer when it should be selected.

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

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

No annotations are present, so the description carries the burden; it openly discloses that an empty color clears and that omitting all match parameters colors every video/audio item, a key destructive edge case. It does not discuss overwrite semantics, match-priority when multiple filters are supplied, or no-match handling, but the most important behaviors are covered.

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

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

Two short sentences, with the primary action and clear behavior front-loaded and matching scope in the second. No filler or repeated schema information.

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

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

For a simple 4-parameter mutation tool with an output schema, the description covers the action, the scoping options, the dangerous no-filter fallback, and the clearing behavior. The only notable omissions are color-value vocabulary and filter-combination rules, which are reasonable gaps given the Resolve-specific context and existing output schema.

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

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

With 0% schema description coverage, the description adds meaningful semantics: the color parameter accepts Resolve color names with empty meaning clear, and the three optional parameters are matching keys with 'if none given' fallback. It stops short of specifying exact accepted color strings or how multiple match parameters combine, but it compensates for the bare schema better than most.

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

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

The description uses a specific verb ('Set') and resource ('Resolve clip color on timeline items'), gives example color values, and explains the clearing behavior. It clearly identifies the tool as the one for coloring clips, distinct from sibling timeline/marker tools.

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

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

It explains matching scopes (unique_ids, media_id, clip_name) and the default behavior when no filter is provided, which tells the agent when it is safe to apply broadly. It does not explicitly name alternatives or exclusions, but there is no sibling that performs clip-color setting, so the context is sufficient.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. 'Diagnose' hints at a read-only operation, but the description does not explicitly state that the tool does not modify state, what kind of diagnostic information it returns, or whether it attempts any connection. The parenthetical clarifies scope but not behavior.

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

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

The description is a single, focused sentence with no wasted words. The main purpose is front-loaded with the verb 'Diagnose', and the parenthetical adds valuable nuance without bloating the text.

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

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

For a zero-parameter tool with an output schema, the description is nearly complete: it states the tool's purpose and the key distinction it diagnoses. It could optionally note that this tool does not perform reconnection or corrective actions, but given the low complexity, the current description is sufficient for selection and invocation.

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

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

The tool has zero parameters, so there is nothing for the description to explain beyond the schema. The schema already fully covers this empty parameter set, and the description appropriately avoids inventing parameter details. The 0-param baseline of 4 applies.

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

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

The description uses a specific verb ('Diagnose') and identifies a precise resource ('Resolve connection') with a meaningful distinction between two connection modes: direct Studio scripting and free-edition in-app bridge. This clearly differentiates the tool's diagnostic purpose from sibling tools like reconnect or inspect.

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

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

The description implies when to use the tool (when connection diagnosis is needed) but provides no explicit guidance on when not to use it or how it relates to alternatives. It does not mention that this is for diagnosis only and not for fixing or reconnecting, leaving the agent to infer the decision boundary.

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

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

With no annotations, the description carries the safety burden; 'Snapshot' strongly implies a read-only operation and the description details exactly what is covered, including the media filtering behavior. It stops short of explicitly stating there are no side effects or providing error behaviors, but for this tool type it is reasonably transparent.

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

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

Two compact, front-loaded sentences: first gives the overall purpose and scope, second defines the optional parameter. There is no filler or repetition of the schema default.

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

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

For a single-optional-parameter inspection tool with an output schema, the description covers what will be snapshotted and the meaning of the media argument. It lacks explicit guidance on when to prefer this over sibling tools, but that is a minor gap given the low complexity.

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

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

The schema provides only the parameter name and default, while the description adds complete meaning for the only parameter: media accepts 'current' (current bin) or 'all' (entire pool). This fully compensates for the 0% schema description coverage.

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

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

Description uses 'Snapshot' as a specific verb and enumerates the scope: app, project, current timeline (tracks, items, markers), and media pool. It clearly indicates this is a broad state-inspection tool, though it does not explicitly distinguish itself from sibling query tools like markers_query or clip_metadata_get.

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

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

Usage context is implied by the word 'Snapshot' and the broad resource list, suggesting it is the tool to call for overall state visibility. However, there is no explicit when-to-use guidance or mention of alternatives such as markers_query for marker detail.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose that this is a destructive delete operation and mentions scope, but it leaves critical behavior ambiguous: whether at least one filter is required, whether multiple filters combine as OR/AND, and what happens when no filter is provided. For a deletion 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.

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

The description is two short sentences with no filler, front-loading the action and then compactly presenting scope options. Every word earns its place, and the terse structure helps an agent parse the core behavior quickly.

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

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

Given no annotations, six parameters, and a destructive operation, the description is not complete enough. It omits how media_id and unique_id relate to item/clip scopes, does not clarify behavior with no filters, and does not state whether the filters are mutually exclusive or combinable. The output schema may cover return values, but call-shaping behavior is under-specified.

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

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

Schema description coverage is 0%, so the description must compensate. It adds meaning to id ('payload id'), color, frame, and scope with its default and allowed values, but it does not explain media_id or unique_id at all. The description partially compensates for the schema gap but not fully.

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

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

The description states a specific delete operation on markers with clear filter dimensions (payload id, frame, or color) and scope options. This clearly distinguishes it from sibling tools like markers_query or marker_upsert, even though no sibling is named.

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

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

The description implies when to use the tool: when markers need to be deleted by id, frame, or color, with timeline as the default scope. However, it does not explicitly state when not to use it or name alternatives such as markers_query or marker_upsert, so the routing 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.

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

With no annotations, the description carries the behavioral burden. It discloses the event structure and the from_clips side effect of stamping clip metadata as clip-scope markers, but it does not state whether existing markers are replaced, cleared, or merged, nor whether the operation requires existing marker types or has destructive effects.

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

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

The description is compact and front-loaded with the core purpose, followed by a dense but justified event schema and the from_clips behavior. There is no filler; every sentence contributes to understanding the tool.

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

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

Despite the useful event schema, the description is incomplete for a mutation-like tool: field_map semantics are absent, side effects are unclear, and no guidance connects this tool to the sibling marker tools. An agent could not confidently predict whether the call adds, replaces, or clears markers.

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

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

Schema description coverage is 0%, so the description must compensate. It substantially documents the events parameter and explains from_clips, but field_map is entirely unexplained, leaving one of three parameters ambiguous for an agent trying to construct a correct call.

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

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

The opening sentence 'Map metadata events onto typed markers' states a specific action and resource, and the inlined event shape clarifies the input format. It does not explicitly contrast with sibling marker tools like marker_upsert or markers_query, so differentiation relies mostly on the tool name and the metadata-focused wording.

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

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

There is no explicit statement of when to use this tool versus alternatives such as marker_upsert, markers_query, or markers_clear. The from_clips note gives a conditional behavior, but the description does not provide overall when-to-use/when-not-to-use guidance or name sibling alternatives.

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

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

With no annotations present, the description carries the behavioral burden. 'Query' clearly signals a non-mutating read operation, and 'Filter' describes selection rather than modification. It does not detail permissions or rate limits, but nothing in the text implies hidden side effects.

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

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

Two short sentences with no filler. The verb and resource are front-loaded, and every phrase adds useful information about what the tool does and how it filters.

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

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

The description covers intent and filter semantics well, and the presence of an output schema means return shape does not need to be described. However, it leaves potential value domains for type/color/scope and frame-range boundary behavior unspecified, so an agent may need external knowledge to make non-trivial calls confidently.

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

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

The schema has 0% description coverage, but the description maps all five parameters into meaningful filter concepts: type, color, scope, and frame range for start/end. This adds real meaning beyond the raw schema, yet it stops short of specifying allowed values, units, or boundary semantics, so compensation is only partial.

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

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

The description uses a specific verb ('Query') and a concrete resource ('timeline, item, and clip markers'), and immediately lists filter dimensions. This clearly distinguishes it as a read-only retrieval tool from write-oriented siblings like marker_upsert and markers_clear.

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

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

The description provides clear context: use this tool when you need to retrieve markers, optionally filtered by type, color, scope, or frame range. It does not explicitly name alternatives or state when not to use it, but the read-only verb makes the intended use unambiguous.

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

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

There are no annotations, so the description carries the full behavioral burden. It does well by disclosing idempotency on payload.id, the create-or-replace semantics, and the special behavior when payload is omitted. It does not mention permission requirements or exact side effects of replacement, but it gives meaningful behavioral context beyond the tool name.

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

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

The description is compact and organized into a concise summary, a field listing, and a usage hint. The 'If payload is omitted' sentence is somewhat confusingly worded, but overall the description earns its length and is not bloated.

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

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

Given the extremely sparse input schema, the description provides essential context about the marker object shape, idempotency, and when to prefer an alternative. The presence of an output schema reduces the need to explain return values. The main gap is the slightly unclear payload-omitted behavior, but the overall context is adequate for an agent to invoke the tool with reasonable confidence.

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

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

Schema description coverage is 0%, so the description must carry the parameter semantics. It does so effectively by enumerating the marker object fields: type/name, frame, optional scope with explicit enum values, color, note, duration, unique_id, media_id, and payload structure. This is substantially more informative than the bare schema, which only declares an array of arbitrary objects.

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

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

The description states a clear action ('Create or replace typed markers') and identifies the resource type, along with the idempotency key ('payload.id'). It does not explicitly differentiate itself from sibling tools like markers_query or markers_clear, though it does mention markers_from_metadata as a preferred alternative for a specific use case.

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

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

The description provides a concrete routing hint: 'Prefer markers_from_metadata for mapping.' This tells the agent when an alternative is better suited. However, it does not explicitly state when marker_upsert should be used versus the other marker-related siblings, leaving some inference required.

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

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

With no annotations provided, the description must carry the behavioral disclosure burden. It clearly states that files are imported into the current media pool folder and that media_id values are returned, which is useful. It does not mention duplicate handling, unsupported file types, or side effects beyond the import, though the action itself is straightforwardly additive.

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

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

Two short sentences with no filler. The main action is front-loaded, and the return value is mentioned separately and clearly. Every word earns its place.

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

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

For a single-parameter import tool, the description is mostly complete: it names the target (current media pool folder) and the return value. Missing context includes what happens if a path is invalid, whether duplicates are skipped, and any media-format restrictions. An output schema exists, so the return shape need not be fully described, but operational edge cases are still absent.

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

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

The schema provides only the parameter name 'paths' with a string-array type and no description; coverage is 0%. The description compensates by clarifying that these are files to be imported and that each produces a media_id for the corresponding clip, which gives practical meaning beyond the raw schema.

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

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

The description states a specific verb ('Import'), a clear resource ('files into the current media pool folder'), and a concrete outcome ('Returns media_id for each clip'). This clearly distinguishes it from the sibling tools, which concern timeline placement, clip color, markers, and metadata operations.

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

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

The description conveys the core use case: importing files into the current media pool folder. However, it gives no explicit guidance on when to choose this tool over alternatives, nor any exclusions or prerequisites such as requiring an open project or an available media pool.

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

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

No annotations are provided, so the description carries the burden of behavioral disclosure. It explicitly discloses the destructive/stateful nature ('Drop the cached session') and the follow-up action (connect again), which is sufficient for a zero-parameter tool.

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

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

One sentence with zero filler; the action is front-loaded and the target is precise. Every word earns its place.

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

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

For a parameterless reset operation, the description covers the essential behavior and the output schema exists to document return values. It is slightly incomplete only because it does not state when this operation is warranted.

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

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

The tool accepts no parameters, so there is nothing for the description to document beyond the empty schema. The baseline for zero-parameter tools applies.

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

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

The description states a specific action ('Drop the cached Resolve session and connect again') with a clear resource ('cached Resolve session') rather than merely restating the name. It also makes clear this is a connection-reset operation, which sets it apart from sibling tools like inspect or doctor.

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

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

No guidance is provided on when to reconnect versus using alternatives, nor are conditions like a stale or failed session mentioned. The intended usage is only implicit in the verb 'reconnect'.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the high-level actions (ensure, import, place) but does not state whether the operation is destructive, whether existing timeline content is cleared or merged, whether it is idempotent, or what side effects media import may have. This is a significant gap for an orchestrating mutation tool.

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

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

The description is brief and front-loaded with the core action, then summarizes the benefit. It wastes no words, though terms like 'ensure' and 'rough cut' are somewhat ambiguous without domain context.

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

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

The tool combines multiple operations, but the description does not explain key contextual details: what happens if the timeline already exists, whether clips are appended or replaced, how optional import interacts with placement, or what constitutes a valid rough cut. The output schema may cover return values, but the operational semantics are under-specified for reliable invocation.

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

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

Schema description coverage is 0%, so the description must compensate, but it only loosely hints at the parameters: 'import media' suggests paths, and 'place clips' suggests items. It never explicitly maps paths to media files or items to clip objects, leaving the agent to infer how to populate the arguments correctly.

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

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

The description clearly states the tool's combined role: ensuring a timeline, optionally importing media, and placing clips to produce a rough cut. It distinguishes itself from siblings like timeline_ensure and timeline_place by advertising a one-call assembly workflow, though it does not name those alternatives explicitly.

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

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

The phrase 'Rough cut in one call' implies this tool is for a consolidated assembly workflow rather than using separate ensure/import/place calls. However, it does not explicitly state when to prefer this tool over the individual sibling tools, nor does it describe exclusions or edge cases such as when not to use it.

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

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

With no annotations, the description carries the behavioral disclosure burden. It does disclose that the tool is idempotent and that it switches to the timeline, which is useful. However, it does not mention what happens to an existing timeline beyond not recreating it, or any side effects beyond switching.

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

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

The description is two short sentences with zero filler. The key conditions 'if needed' and 'Idempotent' are front-loaded, and every phrase adds meaning.

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

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

For a one-parameter tool, the core behavior is covered and an output schema exists, so return details are not required. However, the lack of usage guidance and any mention of alternatives leaves the description incomplete for an agent operating among many timeline-related siblings.

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

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

The schema only provides a required string 'name', and the description adds only minimal meaning by referring to the 'named timeline'. There is no additional detail about name format, uniqueness, or validation, so parameter semantics remain thinly covered.

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

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

The description states a concrete action, 'Create the named timeline if needed and switch to it', with a clear resource and behavioral intent. It is not a tautology and is distinguishable from sibling tools like timeline_place, though it does not explicitly call out sibling differences.

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

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

The description provides no guidance on when to use this tool versus alternatives such as timeline_place or timeline_lift. The phrase 'if needed' implies an ensure-style pattern, but there is no explicit context, prerequisite, or exclusion to help an agent decide.

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

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

With no annotations provided, the description must carry the behavioral burden. It explicitly discloses that deletion is destructive ('Effects on those items are lost'), which is valuable, but it does not explain the meaning of the 'ripple' parameter, track scoping, or whether the operation is reversible. This is partial transparency, not full.

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

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

Two short sentences carry all the essential information with no filler. The destructive nature and selection methods are front-loaded, and every sentence earns its place.

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

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

Although an output schema exists, the operational context is incomplete for a destructive tool with six optional parameters and no required fields. The agent is not told which parameter combinations are valid, what happens if no selection parameters are provided, how ripple affects deletion, or how track_type/track_index confine the deletion.

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

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

The description adds meaning beyond the bare schema by explaining the two selection modes: 'by unique_id' maps to unique_ids, and 'by range' maps to start/end. However, it leaves track_type, track_index, and ripple unexplained, and schema description coverage is 0%, so these gaps are significant.

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

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

The description states a specific verb ('Delete'), a specific resource ('timeline items'), and the two selection mechanisms ('by unique_id or by range'). It clearly distinguishes this destructive operation from sibling tools like timeline_place and timeline_assemble, which are constructive/write operations.

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

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

The description implies this tool is for deletion of timeline items, but it gives no explicit guidance about when to prefer it over alternatives, when not to use it, or any prerequisites. It does not name sibling tools or exclusion conditions, so the usage context is only implied.

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

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

No annotations are provided, so the description carries the full burden. It does not disclose side effects, whether existing clips are overwritten, whether the operation is atomic, what happens on invalid items, or whether a current timeline must already exist. The description only names the action and some item fields.

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

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

The description is compact and front-loaded. The primary action is stated in the first sentence, and the item-field summary follows directly in a scannable format. Every sentence 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.

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

The description is terse enough to be a reference card but leaves important context missing: how the 'current timeline' is determined, what track_type values are valid, how frame values are interpreted, what happens on partial failure, and how this relates to sibling timeline tools. With no annotations, this is a meaningful gap for such a nested-array tool.

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

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

Schema description coverage is 0%, so the description must compensate. It does meaningfully by explaining that each item can be identified by media_id, clip_name, or path, and lists optional placement fields plus the media_type numeric mapping. This gives an agent far more than the bare 'items' array schema, though it still omits types and units for fields like record_frame.

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

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

The description opens with a clear verb+resource statement: 'Place clips on the current timeline.' This is specific and meaningful. However, it does not explicitly contrast with closely related siblings like timeline_assemble, timeline_lift, or timeline_ensure, so it earns 4 rather than 5.

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

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

There is no guidance about when to use this tool versus alternatives such as timeline_assemble or timeline_lift. The description implies the action but not the conditions under which placement is appropriate, what prerequisites exist (e.g., an open timeline), or when another sibling should be chosen.

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

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

With no annotations, the description carries the full burden of behavioral disclosure, but it only defines the registry's contents. It does not state that the call is a read-only lookup, what the returned payload represents, or any side-effect or error behavior.

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

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

A single concise, front-loaded phrase conveys the mapping and enumerates the value domains. There is no redundant or filler content.

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

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

For a zero-parameter registry lookup, the description covers the data model and the output schema is available, so the core call is understandable. However, it lacks explicit read-only behavior and any pointer to when to use it, leaving some context to inference.

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

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

The tool has zero parameters and an empty input schema, so there is nothing for the description to disambiguate. The baseline of 4 applies.

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

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

The description identifies a specific resource (marker type registry) and the data it exposes: id-to-color, scope, and duration. It stops short of an explicit verb, but the name 'get' and the registry framing make the action clear, and the tool is easily distinguished from marker_upsert and markers_query.

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

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

No guidance is given on when to call this tool instead of sibling tools such as markers_query or clip_set_color. There is no stated use case, prerequisite, or condition under which the registry lookup is appropriate.

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