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

Annotations already declare readOnlyHint and idempotentHint, so safety is covered; the description adds useful discovery context about the three categories of information returned. It does not describe the response's shape or ordering, but for a no-argument introspection call the added behavioral value is solid.

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

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

Two sentences, the substantive capability list first and the invocation guidance second, with no filler. Every clause earns its place by naming a distinct piece of returned information or a call trigger.

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?

With no output schema, the description carries the burden of explaining returns, and it does so by enumerating the three categories. It stops short of describing the response structure (e.g., how open projects are listed), which is a minor gap for an agent deciding whether to rely on this call.

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 takes zero parameters, so there is nothing for the description to disambiguate. Baseline of 4 applies; the description correctly implies a self-contained no-argument 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?

States a specific verb ('Report') and resource ('what this server supports'), then enumerates exactly what is covered: readable/writable file formats, Python codec availability for Pivot files, and currently open projects. This is clearly distinguishable from siblings like project_describe or figure_list, which operate on a specific object rather than server-wide capabilities.

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

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

Explicitly says 'Call this first when you do not know what the project looks like yet', giving a clear trigger condition. It does not explicitly name a competing sibling (e.g., project_describe) as the alternative for the case where you do know the project, so it falls short of full when/when-not routing.

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

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

Annotations already declare this is a non-readonly, non-idempotent, non-destructive mutation. Beyond that, the description usefully discloses defaults: placement at the canvas centre when x/y are omitted, and use of the first project definition when figureTypeId is omitted.

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 short, front-loaded with the core action, and organized around placement, frame selection, and definition selection. It has minor repetition of schema-provided defaults but no wasted bulk.

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 five-parameter creation tool with no output schema and clear annotations, the description covers the important behavioral defaults. It does not explain the return value or failure cases, which would be helpful but are not essential for correct 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 100%, so the baseline is 3. The description adds meaningful defaulting semantics not present in the schema, especially for x/y placement and figureTypeId, though it mostly repeats the schema's frame and project defaults.

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 and resource: 'Add a figure instance' to a keyframe using an existing figure definition. This clearly distinguishes it from sibling tools such as figure_duplicate, figure_delete, and figure_transform.

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 clearly explains the default behavior for frame and figureTypeId, giving the agent enough context to decide when to supply or omit those parameters. It does not explicitly compare against alternatives like figure_duplicate, but the usage context is clear.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds a genuinely non-obvious consequence: attached figures are detached and kept rather than cascade-deleted. It stops short of saying whether the removal is undoable via history_undo.

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

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

Three short sentences, front-loaded with the action, then the side effect, then the batch variant. No filler or redundancy.

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

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

For a destructive mutation with no output schema and fully documented parameters, the description covers the key side effect and the batch mode. Minor gaps remain around error behavior and reversibility, both of which matter for a destructive operation.

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

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

Schema description coverage is 100%, so uid, frame, and project are already documented. The description only restates/expands the 'frames' parameter behavior, which the schema itself also describes, so it adds little beyond the baseline.

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

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

The description states a specific verb and resource ('Remove a figure') plus the scope ('from a keyframe'), so it is clearly not figure_add or figure_duplicate. It never names a sibling tool, so the differentiation is inferred from the verb rather than stated.

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 is implied rather than explained: 'Give "frames" to remove it from several keyframes at once' guides one parameter choice, but there is no statement of when to prefer this over figure_transform/keyframe_edit or what happens when the figure does not exist on that keyframe.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds genuine value by disclosing the depth and shape of the returned data — that joints carry handles, parents, lengths, angles, thickness, shape and colour, plus fills, rig and keyframe placement — which matters because there is no 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.

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

Two sentences, front-loaded with the return payload and followed by the targeting rule. The long parenthetical list of joint attributes is dense but each element is informative; minor cost in readability rather than waste.

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

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

With no output schema, the description carries the burden of explaining return values and does so thoroughly (joint attributes, fills, rig, keyframe). Parameter defaults and the project scoping are handled by the schema, so nothing critical is missing, though edge cases (e.g. what happens if neither uid nor figureTypeId is supplied) go unmentioned.

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

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

Schema description coverage is 100%, so all four parameters (uid, frame, project, figureTypeId) are already documented in the schema, including frame defaulting to the playhead. The description's sentence about uid vs figureTypeId largely restates the schema's own descriptions, so it adds little beyond the baseline.

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

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

States a specific verb and resource ("Report one figure in full") and enumerates exactly what is returned: joint geometry (handle id, parent, length, angle, thickness, shape, colour), fills, rig, and keyframe position. This is clearly distinguishable from figure_list, which returns a collection rather than a full single-figure dump.

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

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

Explicitly routes the caller between the two targeting modes: "Name an instance with uid, or a definition with figureTypeId." That is a real use-case decision the agent would otherwise have to infer. No explicit when-not guidance relative to figure_list or pose_evaluate, which keeps it below a 5.

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

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

Annotations already declare this is a non-readonly, non-idempotent, non-destructive mutation. The description adds useful behavior beyond that: the copy includes the pose, is offset so it does not overlap the original, and receives a new id. It does not mention permissions, undo behavior, or whether the original is left untouched, but the annotation coverage lowers that burden.

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?

Four short sentences, front-loaded with the core action. Each sentence adds distinct value: destination, frame selection, offset rationale, and identity behavior.

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 duplication tool with full schema coverage and no output schema, the description gives enough to invoke it correctly. The main missing piece is guidance on when to choose this over related figure tools, plus resolution of the frame-default discrepancy.

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

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

Schema coverage is 100%, so the schema already documents all four parameters. The description adds rationale for the offset and a fallback for the frame parameter, but its statement that the playhead decides the frame potentially conflicts with the schema's claim that frame defaults to the figure's current keyframe, reducing reliability.

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 and resource: copy a figure, including its pose, into a keyframe. This clearly distinguishes it from figure_add (which adds a new figure) and figure_transform (which transforms an existing one).

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 explains how the optional keyframe and offset work, but it does not say when to use figure_duplicate versus figure_add or figure_transform. No explicit alternatives, exclusions, or prerequisites are given.

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

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

The readOnlyHint and idempotentHint annotations already establish the safety profile. The description adds useful behavioral context: it returns figure attributes plus stored keyframes, and frame selection depends on either the supplied frame number or the playhead. It does not discuss pagination behavior for the limit parameter, which is a minor omission.

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

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

Three sentences, each carrying distinct information: what is listed, how frame selection works, and how to use the returned ids. It is front-loaded with the core purpose and contains no filler.

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

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

For a read-only listing tool with full schema coverage and annotations, the description is nearly complete: it names the returned figure fields and keyframes, explains frame behavior, and directs reuse of ids. It could mention the default limit or pagination behavior, but that is already present in the schema and not essential.

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

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

Schema description coverage is 100%, so all five parameters are already documented in the schema. The description adds some meaning around frame selection (keyframe number versus playhead) but does not add detail for name, layer, limit, or project beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description gives a specific verb and resource: 'List the figure instances the animation shows,' and enumerates the returned fields (ids, names, layers, position, scale, opacity, colour, keyframes). This is enough for an agent to distinguish it from figure_describe or layer_list without opening the schema.

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 clearly explains the key usage condition: supply a keyframe number to list figures at that moment, otherwise the playhead determines the frame. It also says to reuse returned ids with other figure and pose tools. It does not explicitly state when to prefer figure_describe over figure_list, but the listing use case is clear.

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

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

Annotations already disclose this is a non-read-only, non-idempotent, non-destructive mutation, so the description only needs to add context. It usefully adds that angles are degrees and anticlockwise and that multiple uids move together, but says nothing about whether changes apply across one keyframe vs the timeline, or persistence/undo implications, which matter for a 13-param mutator.

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

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

Three tight sentences: the capability list leads, then a units/orientation caveat, then the multi-figure behaviour. No filler and the most surprising detail (multi-select grouping) is not buried.

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?

With no output schema, an agent gets no indication of what the tool returns or how success/failure is reported after a mutation. The schema is fully described, which covers parameters, but the behavioural envelope of a 13-param, non-idempotent transform is only partly addressed.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds genuine semantic value beyond the schema by clarifying rotation direction (anticlockwise) and the co-movement semantics of 'uids'. It does not, however, add anything on frame vs frames or on how 'order' interacts with layers.

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?

States a specific verb family (move, rotate, scale, flip, align, centre, reorder) on a specific resource (a figure), so it is clearly distinct from figure_add, figure_delete, and figure_duplicate in the sibling list. An agent knows exactly what class of operation this is.

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 is implied by the enumerated actions, but there is no explicit 'use this when…' or 'use X instead for…' routing. Note that keyframe_edit, pose_set, and figure_describe exist as siblings and the description never states the boundary between transforming geometry and editing animation or poses.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), so the bar is lower. The description adds scoping ('in the open project') and stack semantics, but says nothing about failure behavior when nothing has been undone or what the call returns, which matters for a state-mutating history operation.

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

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

One sentence, front-loaded with the verb, no filler. It conveys scope and ordering semantics without redundant restatement of the tool name.

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-optional-parameter tool with annotations covering safety and no output schema, this is largely sufficient. The only meaningful gaps are empty-stack behavior and confirmation of what a successful redo affects, which are modest for this complexity.

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

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

Schema description coverage is 100% and the single optional 'project' parameter is fully documented in the schema, including its default. The description only gestures at project scope via 'open project', so it adds no meaning beyond the schema — baseline 3.

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?

States a specific verb ('Redo') plus the exact resource affected ('the change that was last undone') and its scope ('in the open project'). It is clearly distinguishable from history_undo by the 'last undone' qualifier, though it never names the sibling 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 'last undone' implies the tool is used to reverse a history_undo, which is useful implicit routability. However, there is no explicit when-to-use statement, no guidance on what happens when the redo stack is empty, and no direct reference to history_undo as the counterpart.

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

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

Annotations already declare mutation, idempotency, and destructive behavior. The description adds valuable context beyond that: the one-step-per-tool-call granularity and the need for repeated calls to undo multiple changes. It does not cover edge cases such as no undo history or permission constraints, but its added value is solid.

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

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

Three short sentences, front-loaded with the core action and followed by two clarifying sentences that each earn their place. 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?

For a simple mutation tool with full parameter documentation and complete annotation coverage, the description provides enough to call it correctly. Minor gaps remain around edge cases (nothing to undo, cross-project history) but nothing essential is missing.

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?

There is only one optional parameter and the schema already describes it fully (100% coverage), including the default to the most recently used project. The description adds no parameter 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.

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

The description states a specific verb and resource: 'Undo the last change to the open project.' It clearly distinguishes the action from non-undo tools. However, it never names the obvious sibling history_redo, so an agent must infer the boundary from tool names alone.

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 gives clear usage context: call once to reverse one tool call, and repeat to undo further changes. It does not state when not to use it or explicitly redirect to history_redo, leaving that comparison 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?

Annotations already declare the tool as destructive, non-idempotent, and non-read-only. The description adds meaningful domain behavior: a keyframe is a stored pose, adding copies the current pose, and multiple keyframes can be acted on at once. It stops short of explicitly warning that deleting keyframes destroys stored poses, but the pose/file-keeping sentence and the annotations together convey that.

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

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

The description is three sentences, front-loaded with the core purpose and action list. It is efficient, though the sentence about a keyframe number being a stored pose is slightly abstract and could be clearer.

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 destructive multi-action tool with full schema coverage and no output schema, the description supplies the essential conceptual model: what a keyframe is, how add behaves, and how to act on several at once. It does not cover error conditions or undo behavior, but those are not required for correct 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 100%, so the baseline is 3. The description adds semantic value by explaining what a keyframe number represents and what "frames" does for batch operations, which helps the agent reason beyond the raw field descriptions.

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

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

The description gives a clear verb-and-resource purpose (change the timeline by adding, deleting, duplicating, or moving keyframes) and enumerates the exact actions. It does not explicitly differentiate itself from the sibling keyframe_timing, which likely also edits keyframe-related data, so sibling differentiation is only implicit.

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 action list implicitly tells the agent what operations are available, and the note about using "frames" for multiple keyframes is helpful. However, there is no explicit when-to-use guidance, no exclusions, and no mention of when to prefer keyframe_timing or pose tools instead.

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

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

Annotations already declare mutating but idempotent and non-destructive, so the safety profile is covered. The description adds useful domain semantics (ticks as the length unit, keyframe number = stored pose), but it omits the real behavioral question for this tool: whether changing fps or canvas size rescales existing keyframe timing/content.

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

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

Three short sentences, front-loaded with the three modes so an agent knows the shape of the tool immediately. The final sentence about keyframe numbers being stored poses is slightly cryptic but earns its place as disambiguation.

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 an 8-parameter mutation with no output schema, the description covers the three action modes and the key units, and annotations cover reversibility. It still leaves gaps an agent would want: whether the canvas resize affects existing layer positions, and how an fps change interacts with existing keyframe durations.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond it by explaining the ticks unit and giving the 24 fps = 24 ticks conversion, which makes the otherwise opaque 'ticks' bound meaningful. It also clarifies that 'frame' refers to a stored pose, disambiguating it from the 'frames' array.

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 gives a specific verb ('change') and enumerates the three concrete resources it operates on: keyframe length, project frame rate, and canvas size, which map directly onto the 'action' enum. It is clear what the tool does, but it never distinguishes itself from the sibling keyframe_edit, which plausibly also touches keyframes.

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 is implied by the action enum (duration/fps/canvas) and the per-parameter descriptions, but the prose adds no explicit 'use this when' or 'use keyframe_edit instead' guidance. An agent can infer the routing from the enum, but nothing is stated about prerequisites such as an open project or a valid playhead.

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

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

The description is consistent with annotations (destructiveHint=true, non-idempotent) since it advertises delete as one of the actions, but it does not isolate which actions are destructive, whether deleting a layer destroys contained figures, or whether the operation is undoable via history_undo. With annotations already declaring the safety profile the bar is lower, so the added 'multi-action dispatcher' framing earns a middling score.

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 action enumeration is front-loaded and each item earns its place by mapping to a real enum value. The closing sentence 'Give the action and the fields it needs' is redundant filler given the required action parameter.

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

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

For a 9-parameter mutation tool with no output schema, the description covers the operation set but leaves material gaps: what delete does to contained figures, whether operations are recoverable, and what the response reports. Cross-referencing history_undo for reversal would have closed the largest gap.

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

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

Schema description coverage is 100% and every parameter already documents the action it applies to, so the baseline is 3. The description adds nothing beyond 'give the action and the fields it needs' — no constraint such as reorder requiring the complete layer id list, or assign requiring both uids and layerId.

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?

Names a specific verb (change/edit) plus resource (project layers) and enumerates every supported operation — create, rename, delete, reorder, assign, visible, lock — which maps one-to-one onto the action enum. An agent can immediately distinguish this mutation tool from the read-only sibling layer_list without opening either schema.

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 action list implies when each mode applies, and 'Give the action and the fields it needs' tells the agent how to invoke it. But there is no explicit when-not guidance, no mention of prerequisites such as an open project (only inferable from the project parameter description), and no hand-off to siblings like layer_list or history_undo.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds genuinely useful behavior: it operates on the open project, and it discloses the fields returned, notably the layer ids needed downstream. It doesn't cover failure modes (no open project) or ordering, which keeps it from a 5.

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

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

Two sentences, zero waste, with the return payload front-loaded and the downstream chaining instruction second. Every clause 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?

No output schema exists, so the description must convey return values — and it does, listing ids, names, visibility, lock state and contained figures. Combined with the schema-documented project parameter and annotations, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100% and the single project parameter is fully documented in the schema, including its default. The description adds nothing about the parameter — baseline 3 applies when the schema does the work.

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?

Specific verb+resource (list the layers of the open project) plus an enumeration of what each entry carries (ids, names, visibility, lock state, figures). It is clearly distinguishable from figure_list and layer_edit without opening either schema.

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

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

Explicitly routes the agent forward: 'Use the layer ids this returns with layer_edit and figure_transform.' That establishes the prerequisite relationship with the mutating siblings. It stops short of stating when not to use it or an alternative for filtered listing, but 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.

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

Annotations already declare readOnlyHint and idempotentHint, so safety is covered; the description adds the coordinate space (canvas pixels), that segments and IK controller state are included, and that segments are per-segment endpoints. With no output schema it still leaves the returned data structure unnamed, which keeps it below a 5.

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

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

Three tight sentences: what is returned, when to use it, and how to specify the time; the operative information is front-loaded. The final sentence largely restates the tick schema field, so a small amount of redundancy remains.

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 read-only evaluation tool with no output schema, the description adequately sketches the return payload (joints, segment endpoints, IK state) and the time-selection mechanism. It does not describe result shape or whether uids filtering changes the payload layout, a minor gap.

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

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

Schema coverage is 100%, so the schema already documents tick, frame, uids, project and includeSegments. The description adds only the tick-vs-keyframe precision distinction (and that tick overrides frame-based selection), which is a marginal gain over the schema's own wording.

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?

Names a specific verb (read/evaluate) and a precise resource (the solved rig at a point in the animation), and enumerates what the read yields: joint positions in canvas pixels, segment start/end points, and IK controller state. This is clearly distinct from the mutation siblings pose_set, pose_reset and pose_ik_set without needing their schemas.

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?

Gives concrete usage contexts: locate a hand or foot before modifying it, and verify a pose after modifying it. It does not explicitly rule out alternatives (e.g. figure_describe or pose_ik_set) for overlapping questions, so there is no exclusion guidance.

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

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

Goes beyond the annotations by disclosing state preconditions (controller must be enabled) and the pinned-vs-unpinned consequence ('an unpinned one bakes the pose'), which is real behavior an agent cannot get from readOnlyHint=false alone. Minor tension: 'bakes the pose' implies a persistent write while destructiveHint=false, though this is an unannotated nuance rather than a flat contradiction.

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

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

Three tight sentences, front-loaded with the action, then the precondition, then the state nuance. Every sentence carries information; only the pinned/unpinned sentence is slightly compressed for what it conveys.

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?

No output schema and six params at full schema coverage, so the description only needs to cover behavior. It covers the precondition and the pinning outcome but leaves the frame/canvas interaction and failure mode (no controller present) implicit.

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

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

Schema description coverage is 100%, so x/y, uid, handleId, frame, and project are already documented. The description adds the useful framing that x/y position a hand or foot target in canvas space and that handleId must be a joint with a controller, but adds no detail on frame semantics or defaults 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?

States a specific verb+resource ('Move the inverse kinematics target of a joint') and clarifies the effect in concrete terms ('placing a hand or foot at a point on the canvas'). It does not, however, distinguish itself from the near-identically named sibling pose_set_ik or from pose_set, so an agent must infer which pose tool to use.

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?

Gives an explicit prerequisite — the controller must already be enabled on that joint — and names the sibling that reveals it ('use figure_describe to see which joints have controllers'). It stops short of saying when to prefer this over pose_set_ik, which is the main ambiguity an agent faces here.

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

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

Annotations already declare non-readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds genuinely useful effect detail — what is dropped (angles, lengths, bends) versus what survives (position, size, colour) — going beyond the annotation set, though it says nothing about scope across frames or reversibility via history_undo.

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 tight sentences: the action first, then the preservation guarantee. No filler and nothing front-loaded incorrectly.

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 four-parameter mutation with no output schema, the description covers the semantic effect an agent most needs to know. The only gap is how the frame/frames parameters scope the reset, which is left entirely to the schema.

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

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

Schema coverage is 100% and each parameter (uid, frame, frames, project) is documented in the schema, so the baseline is 3. The description adds no meaning about frame vs frames or the default playhead behavior, but is not required to.

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?

States a specific verb and resource ('Return a figure to the rest pose of its definition') and enumerates exactly which attributes are discarded (angles, lengths, bends), which distinguishes it cleanly from pose_set or pose_evaluate without needing the siblings 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 the use case (undo a posed state back to the definition's rest pose) but never explicitly contrasts it with pose_set or says when a reset is preferable to setting individual angles. Usage is inferable rather than stated.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds genuinely non-obvious behavior: the whole call collapses into a single undo step, angles are absolute relative to the parent joint, and world placement respects inverse kinematics.

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?

Four tight sentences, front-loaded with the core action, then addressing/units, then the IK alternative, then the undo guarantee. No padding or restatement of the title.

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?

Covers action scope, joint addressing, angle convention, IK behavior, and undo semantics for a 6-param nested-schema tool with no output schema. It leaves open whether a keyframe must already exist at the target frame and does not route to pose_set_ik when the caller wants IK-solved posing.

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

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

Schema coverage is 100%, so baseline is 3; the description earns above that by explaining that handleId comes from figure_describe, that angle parameters are absolute and measured from the parent joint, and that x/y trigger IK rather than a raw overwrite. It does not clarify the relationship between index and handleId when both are supplied.

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?

States a specific verb and resource ('Change a figure's pose in one keyframe') and enumerates the three things it does: root move, scale, joint angle/length/position. An agent can tell this apart from pose_evaluate, pose_reset, and the IK siblings without opening a schema.

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?

Gives clear operating context: joints are addressed by handle id (explicitly sourced 'from figure_describe') or by segment index, angles are absolute from the parent joint, and world x/y is the IK-respecting alternative. It stops short of naming pose_set_ik/pose_ik_set as the explicit alternative for IK-driven posing.

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

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

The description adds one useful behavioral detail beyond the annotations: enabling a controller creates it at the joint's current position so the pose does not jump. Annotations already disclose that this is a non-readonly, non-idempotent, non-destructive mutation, but the description does not explain other side effects such as what happens when disabling or unpinning.

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 sentences with no filler, and the main operation is front-loaded. The behavioral caveat is placed immediately after the operations it qualifies.

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 nine-parameter configuration tool with full schema coverage and annotations present, the description covers the main operations and one important behavioral nuance. It is sufficient to call correctly, though it could say more about alternative IK tools and edge cases.

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

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

Schema description coverage is 100%, so all nine parameters are already documented in the input schema. The description groups several parameters conceptually (enabled, pinned, allowStretch, chainLength), but it does not add syntax, defaults, or constraints beyond what the schema provides.

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

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

The description states a specific verb and resource: configuring a joint's inverse kinematics controller. It clearly enumerates the operations (enable/disable, pin/unpin, allow stretch, change chain length), but it does not differentiate this tool from the sibling pose_ik_set.

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 enumerated operations imply when the tool is used, and the note about enabling explains a consequence. However, it gives no explicit guidance on when to use this versus alternatives such as pose_ik_set, nor any prerequisites or exclusions.

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

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

Annotations already flag destructiveHint=true, but the description adds the crucial specifics: unsaved changes are discarded and the editor is released. That goes beyond a generic 'destructive' label by telling the agent exactly what is lost. It stops short of describing error behavior for a project that isn't open, so not a 5.

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, zero waste, with the destructive consequence and the save prerequisite front-loaded before the agent commits.

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, no-output-schema tool with full annotation coverage, the description supplies the one thing annotations cannot: the data-loss consequence. Only the failure mode for a non-open or unknown project is unaddressed, which is minor.

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

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

Schema coverage is 100% and the single parameter's default behavior ('Defaults to the project used most recently') is already documented in the schema. The description adds nothing about the project parameter, so the baseline 3 applies.

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

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

States a specific verb and resource ('Close an open project') plus the side effect on the editor ('release its editor'), which distinguishes it cleanly from siblings like project_open and project_save. An agent can identify the operation without opening the schema.

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?

Names the alternative explicitly ('save first with project_save') together with the condition that triggers it (unsaved changes will be discarded). The prerequisite is stated as a directive rather than left to inference.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds useful behavioral context by explaining that the default response is a summary and that include adds extra sections, although it does not discuss pagination or how limit affects the returned sections.

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

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

Two sentences, front-loaded with the resource and reported sections, followed by the include/default behavior. Every sentence earns its place with no wasted wording.

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

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

There is no output schema, but the description still conveys the available content categories and the difference between summary-only and include-section responses. It does not explain output formatting or pagination, but the read-only annotations and fully documented schema cover the remaining critical context.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema. The description reinforces the include parameter's default-summary behavior but adds no syntax, formatting, or limit-interaction details beyond what the schema provides; baseline 3 is appropriate.

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

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

States a specific verb and resource: report the structure of the open project, enumerating canvas, frame rate, keyframes, figure definitions and instances, layers, backgrounds, effects, movieclips, and audio. The project-level scope implicitly distinguishes it from sibling tools like figure_list and layer_list, but it does not explicitly name those alternatives.

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?

Explains that the include list selects extra sections and that omitting it returns only the summary, which is clear usage guidance for the main parameter. It does not explicitly say when to use this tool instead of figure_list or layer_list, nor does it mention the project_open prerequisite, though the schema's project parameter does.

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

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

Annotations already declare readOnly/idempotent/openWorld, and the description reinforces this with 'Opening a file does not change it' and discloses the dual read mechanisms (JS direct vs bundled Python codec for Pivot). It also promises a return of project id plus summary. Missing: failure behavior for missing/unsupported files, minor given the read-only annotations.

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

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

Three sentences, front-loaded with the action and effect, then format support, then return value and the non-mutating guarantee. Every sentence carries distinct information; the JavaScript/Python codec detail is the only mildly implementation-flavored bit and it justifies the extension list.

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?

No output schema exists, yet the description states what is returned (project id plus a project summary), which is exactly what an agent needs to chain into later tools. It leaves unstated what happens when a project is already open, but idempotentHint covers much of that.

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

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

Schema coverage is 100% so the single 'path' parameter is already documented. The description nonetheless adds real meaning by enumerating the accepted extensions (.styk, .stkz, .stykmov, .piv, .stk), which tells an agent what kind of value is valid — beyond the schema's generic 'absolute or relative path'.

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?

States a specific verb (open) and resource (StykAnimate/Pivot project file) and adds the scope detail that it 'makes it the active project' and returns a project id. The supported extension list separates it from siblings like project_close or project_describe without requiring schema inspection.

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

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

Clear about the context of use — open a project file, which then becomes active and yields an id that 'later tools accept', implying this is the entry point before project_describe/layer_list. It does not explicitly name an alternative or exclusion (e.g. what to do if a project is already open or how to inspect rather than open), 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.

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

Annotations already flag destructiveHint=true and non-idempotent, so the safety bar is lower. The description adds real value beyond them: atomic full-write-then-replace so a failure leaves the previous file intact, plus the external codec dependency for Pivot formats.

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?

Front-loads the core action, then packs format, figure-selection, atomicity and path defaults into one tight paragraph with no filler. It is dense but every sentence carries distinct information, though a bulleted split for formats could improve scanability.

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?

Covers the five zero-required parameters, format quirks, figure targeting, and write-failure behavior — enough for an agent to call it correctly without an output schema. Only the return value/shape is unaddressed, which is minor for a save operation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description still adds meaning the schema lacks: the interplay between figureTypeId/figureUid (both omitted = first figure in project) and the 'save beside the opened file' default for path. Only the project parameter's default behavior is left to 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?

States a specific verb and resource ('Write the open project to a file') and then enumerates the exact format set, which no sibling tool offers. An agent can distinguish it from project_close or project_describe purely from the description.

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 gives per-format selection guidance ('styk' for project, 'stkz' for a single figure, 'stykmov' for a movieclip, 'piv'/'stk' needing the Python codec) and the figure-selection rule when both ids are omitted. It does not point to sibling alternatives or say when not to save, but the decision context is clear.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds meaningful behavioral context beyond that: the playhead position affects which keyframe subsequent tools target by default, which is important state-management information.

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

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

Two sentences, front-loaded with the action and followed by the key consequence. Every sentence earns its place and there is no redundant restatement.

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, fully-described three-parameter navigation tool with read-only/idempotent annotations and no output schema, the description covers purpose and the important downstream effect. Minor omissions such as default project behavior are already handled by the schema.

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

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

Schema description coverage is 100%, and the schema already explains tick, frame, and project. The description mentions 'keyframe' and 'absolute tick' but adds no syntax, exclusivity, or defaulting details beyond the schema, so baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Move the editor's playhead.' It also clarifies the two positioning modes ('to a keyframe or an absolute tick'), which distinguishes this selection/navigation tool from siblings like keyframe_edit or project_timeline.

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 second sentence gives clear contextual guidance: moving the playhead determines which keyframe later tools edit when no frame is named. It does not explicitly state when not to use the tool or name an alternative, so it falls short of a full when/when-not/alternatives statement.

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

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

The annotations already declare that the tool is read-only and idempotent, so the bar is lower. Because there is no output schema, the description carries the disclosure burden, and it does so by explaining the playback and keyframes structure and by stating that the playback count equals the frame numbers used by the pose and figure tools.

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?

Four short sentences that are front-loaded with the core purpose, and the section definitions come before the filtering hint. Each sentence explains a distinct concept, 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?

There is no output schema, so the description must explain the return shape, and it does so for both sections. It omits the pagination limit semantics and the meaning of the default project, but both are covered in the schema, so the definition is nearly complete.

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

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

The schema documents all 4 parameters at 100% coverage, which sets a baseline of 3. The description does add meaning beyond the schema by saying that fromTick and toTick narrow the playback list specifically, which the schema does not state, because the schema describes them only as 'places'.

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 the specific verb 'List' with the resource 'timeline of the open project', and it names the two returned sections (playback and keyframes). It never contrasts itself with siblings such as project_describe, keyframe_edit, or keyframe_timing, so an agent has to infer the boundary between them.

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 one usage lever, 'Give fromTick and toTick to narrow the playback list', and it links frame numbers to the pose and figure tools. It gives no explicit when-to-use or when-not-to-use guidance relative to keyframe_edit, keyframe_timing, or project_describe, so the usage 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?

Annotations already declare readOnlyHint and idempotentHint, so safety and repeatability are covered. The description adds genuinely useful detail that the check stops at the first problem rather than returning all issues, which an agent needs to know. It says nothing about cost, side effects on the open document, or the shape of the result, so it is a modest addition rather than rich context.

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

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

Two tight sentences, front-loaded with what the tool does and followed by the triggering contexts. Every clause carries information, though the 'or confirm that the project is valid' clause slightly restates the first sentence.

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, single-parameter read-only tool the description covers purpose, trigger, and the meaning of a result (first problem vs. valid), which substitutes for the absent output schema. It stops short of indicating what a reported problem looks like or whether validation can be expensive on large projects.

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?

There is one optional parameter and schema description coverage is 100%; the schema already explains that it takes an open project id and defaults to the most recent project. The description adds nothing about the parameter, so baseline 3 applies.

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

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

Names a specific verb (validate) and resource (the open project), and specifies the validation engine ('the editor's own document validation'), distinguishing it from anything else in the sibling list. No other sibling performs validation, so the unique role is unambiguous.

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

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

Gives two concrete triggers: after edits a client rejected, and before saving. That is clear situational guidance with no real alternative to exclude, since no sibling does validation. Lacks any explicit 'not needed when' condition, which is why it falls short of a 5.

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

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

Annotations already establish idempotent, non-destructive, write behaviour, and the description adds genuinely new context: that a figure colour propagates to every keyframe containing the figure and that a part colour mutates the shared figure definition so all instances change. That cascading side effect is exactly the kind of hidden blast radius an agent needs. It stops short of saying whether changes are undoable via history_undo or what an invalid colour yields.

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?

Four sentences, front-loaded with the capability statement, then the two non-obvious propagation rules, then value formatting. The opening sentence is a long enumeration but every clause maps to a distinct target, so nothing is wasted.

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 10-parameter mutation tool with no output schema, the description covers what each target restyles, the indirect effects, and the value format, while the schema handles per-parameter applicability. It leaves the return value and error behaviour unexplained, but with 100% schema coverage and safety annotations those are modest omissions.

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

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

Schema coverage is 100%, so the schema already documents all ten parameters including per-target applicability (uid, layerId, handleId, frames). The description adds colour syntax ('#rrggbb' or three RGB bytes), but its blanket statement omits the layer special case where the schema requires a palette name — a small gap that the schema has to correct.

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 (change) plus the exact resources it applies to — figure colour/opacity, part colour/thickness, layer colour, and scene background — which maps cleanly onto the four `target` enum values. This differentiates it from nearby mutators such as figure_transform and layer_edit, which touch geometry and layer metadata rather than appearance.

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 is implied by the enumeration of targets, and the scope rules ('a figure colour applies to every keyframe the figure appears in', 'a part colour changes the shared figure definition') tell the agent the consequences of choosing one target over another. However, no sibling tool is named as an alternative, and there is no explicit when-not-to-use guidance (e.g. when to prefer layer_edit or figure_transform).

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