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

Annotations already cover the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=false). The description adds genuinely new context beyond them: that support is layer-dependent, that it returns the new array count, and how to discover the resulting attribute path — all useful for a non-idempotent mutation. It doesn't warn about repeated calls duplicating attributes, but the non-idempotent hint covers that risk.

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 tightly written sentences with no filler; the support constraint and return value come first and the follow-up tool pointer last. Every clause carries actionable 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?

With no output schema, the description usefully discloses the return value (new array count) and the discovery path for the created attribute, plus the layer-support caveat. For a simple 3-parameter mutation this is close to sufficient, though a note on failure modes for unsupported layers would round it out.

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 (type, attrId, layerId) are already documented in the schema, including the default for attrId and an example layer id. The description adds no parameter-level detail beyond that, 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?

States a specific verb+resource ('Add a dynamic attribute') plus a real scope constraint ('layers that support them, e.g. JavaScript layers'), which meaningfully narrows it against siblings like cavalry_set_attributes or cavalry_create_layer. It stops short of explicitly contrasting with those siblings, so it doesn't quite reach a 5.

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

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

Gives a clear condition for use (only layers supporting dynamic attributes) and names a follow-up tool (cavalry_list_attributes) to locate the new attribute path. There's no explicit when-not-to-use or direct alternative comparison against cavalry_set_attributes, so it's clear context without 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?

Goes well beyond the annotations: it discloses sequential ordering, fail-fast termination at the first error, and explicitly that earlier operations are NOT rolled back — the exact partial-failure semantics an agent must know before batching destructive writes. This is precisely the kind of behavior annotations cannot express.

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-loaded with purpose and the critical failure-semantics caveat before the payload format, then closes with a concrete two-step example. Every sentence carries information; nothing is redundant with the schema or annotations.

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-return dispatcher with no output schema, the description covers ordering, failure behavior, op naming, and result referencing. It leaves the response shape on partial failure (what the caller gets back after the stop) unstated, which is the one gap worth closing.

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%, yet the description fully specifies the item shape ({'op','args'}), the naming convention that maps 'op' onto sibling tool names (tool name minus the 'cavalry_' prefix), and the '$<index>' result-referencing syntax including path traversal ('$2.created.0.id'). That reference syntax is not derivable from the schema and is essential to using the tool 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?

States a specific verb and resource ('run several operations in one round-trip, in order') and is immediately distinguishable from every single-operation sibling, since it is the only tool that composes them. An agent can tell this is a meta-dispatcher 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?

The framing 'run several operations in one round-trip' clearly signals the condition that selects this tool over the individual siblings, and the ordering/atomicity note adds operational context. It stops short of an explicit exclusion (e.g. 'use the individual tool when you only need one operation'), so it falls just short of 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 readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=false, so the mutation/safety profile is covered. The description adds only the force=true replacement example, which duplicates the schema's force description, and says nothing about failure modes (e.g. connecting when a connection already exists without force) or what the call returns.

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 core action and immediately followed by concrete wiring examples; nothing is padded or redundant.

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 connection-mutating tool with no output schema and full schema coverage, the description covers what the operation does and how attributes map. It leaves unaddressed the behavior when a connection already exists without force and whether it reports success or failure.

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 adds conceptual meaning the schema lacks: that a layer's main output is its "id" attribute, which explains why fromAttrId defaults to "id". The worked examples also clarify how from/to pairs are composed in practice.

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 ("Connect an output to an input") and backs it with two concrete examples of source->target wiring, so the agent can tell this is the connection-creating tool. It does not name its obvious counterparts (cavalry_disconnect, cavalry_inspect_connections), so sibling differentiation is left 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 examples imply the typical use (wiring a layer's id output into another layer's input attribute) and show force=true for replacement, but there is no explicit when-to-use/when-not guidance, no mention of when to disconnect first, and no statement of prerequisites beyond the schema's pointer to cavalry_list_layers.

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, idempotentHint=false, destructiveHint=false, openWorldHint=false), so safety is largely covered. The description adds the atomic create-plus-attribute behavior, which is real added value, but says nothing about what the call returns, whether attribute paths must already exist, or what happens on an unknown layer type.

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 front-loaded sentence with the core action first and the optional capability second. The type examples earn their place by clarifying the accepted value space, and there is no padding.

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 creation tool with no output schema, the description should say what comes back (e.g. the new layer id/handle) so the agent can chain follow-up calls like cavalry_set_parent or cavalry_set_attributes. That link is missing, though the required-parameter and attribute-map semantics are otherwise adequately covered.

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 (name, type, attributes) are already documented in the schema, including the same type examples the description repeats. The description adds no syntax or format detail 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?

States a specific verb and resource ('Create a layer') and scopes it broadly with concrete type examples ('null', 'group', 'textShape', 'duplicator', 'colorMaterial', 'javaScript'), so an agent knows this is the generic layer factory. It does not, however, distinguish itself from the sibling cavalry_create_primitive, which is a plausible alternative for a subset of these types.

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 clause 'optionally set attributes in the same call' implies a usage pattern (create and configure atomically rather than chaining cavalry_create_layer + cavalry_set_attributes), which is genuinely useful. But there is no explicit when-to-use guidance, no when-not, and no routing against cavalry_create_primitive or cavalry_duplicate_layer.

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=false, idempotentHint=false, and destructiveHint=false, so the safety profile is covered structurally. The description adds only that attributes can be set atomically in the same call; it says nothing about where the layer lands, whether it becomes selected, or error behavior, so it is marginally better than the annotations alone.

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

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

A single sentence that front-loads the core action and appends the optional attribute behavior and a concrete example. 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?

Adequate for a creation tool but incomplete in ways an agent would care about: no output schema exists, yet the description never says what is returned (e.g. the new layer's id/name) that would be needed for follow-up calls like set_attributes or set_parent, nor which composition the layer is added to.

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's attribute-map example (generator.dimensions, position, material.materialColor) largely restates the schema's own example, adding little new semantics; 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 (create) and resource (primitive shape layer) and enumerates valid primitive types, which distinguishes it reasonably from the generic cavalry_create_layer. It does not, however, explicitly route the agent between the two creation tools, so a 4 rather than a 5.

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

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

The phrase 'optionally set attributes in the same call' implies you'd use this instead of a create-then-set_attributes two-step, which is useful implied guidance. There is no explicit statement of when not to use it or which sibling to prefer for non-primitive layers, so it stays at 3.

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 readOnlyHint=false, so the agent knows this mutates state destructively. The description usefully notes that omitting frames removes ALL animation, disclosing the escalation in destruction scope, but this same fact is already present in the frames schema description, so it adds limited context beyond structured data.

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

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

A single sentence with the verb front-loaded and no filler. Both operational modes are conveyed compactly, and nothing extraneous is included.

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 three-parameter destructive mutation, the description covers the purpose and both deletion modes, and the annotations carry the safety profile with no output schema needed. It is largely complete, with only minor gaps such as reversibility/undo behavior left unstated.

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 meaning of attrId, layerId, and frames is fully documented in the schema itself. The description restates the frames-omission semantics without adding new syntax or format detail beyond what the schema provides, 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?

Names a specific verb (delete) and resource (keyframes on an attribute) and scopes the two modes: targeted deletion by frame or full-animation removal when frames is omitted. It is clear what the tool does, though it never explicitly contrasts itself with the sibling cavalry_set_keyframes or add-keyframe flows.

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 condition for the two deletion modes is described (frames present vs omitted), which implies when each form applies. However, there is no explicit guidance on when to reach for this versus cavalry_set_keyframes or other animation tools, and no prerequisites or warnings are 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 destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is covered. The description still adds genuine context beyond them: nonexistent ids are reported back rather than raising an error, implying partial-success semantics the agent could not infer from the annotations alone.

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

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

Two short sentences, front-loaded with the core action and followed immediately by the failure-mode caveat. Nothing is wasted or redundant.

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 carries the return-value burden, and it does disclose what happens to invalid ids. For a single-parameter destructive tool whose annotations already cover reversibility, this is nearly complete; it could say more about whether deletion is immediate or scoped to the current scene.

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 required parameter (layerIds) is fully documented in the schema. The description's 'one or more layers' restates the array without adding id syntax, ordering, or batching detail, 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 (delete) and resource (layers) with cardinality ('one or more'), so an agent can distinguish it from create_layer, rename_layer, or delete_keyframes. It does not explicitly name a sibling or contrast with related tools, so it stops short of a 5.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives such as duplicating/renaming layers instead. The only guidance is negative-case behavior (nonexistent ids do not fail), which is behavioral rather than usage-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 readOnlyHint=false, destructiveHint=true and idempotentHint=false, so the safety profile is fully carried by structured data. The description adds nothing beyond a restatement of the removal: it doesn't say what happens if no connection exists, whether the call errors or no-ops, or that the effect on existing links is irreversible. No contradiction with annotations.

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

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

One short, front-loaded sentence with no filler. It is efficient, though for a destructive operation it is arguably too terse to be fully 'appropriately sized'.

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 operation is low-complexity and the schema is fully documented with no output schema, so little is strictly required. Still, a destructive unlink tool omits error/edge-case behavior and any routing to the connect/inspect siblings, leaving a modest but real 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%, including path examples ('position.x') and the note that fromAttrId defaults to 'id', so the schema carries the parameter burden. The description contributes zero additional parameter meaning, which is the baseline 3 case.

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: 'Remove a connection between two attributes.' That is unambiguous and distinguishable from cavalry_connect, cavalry_inspect_connections and cavalry_set_attributes. It does not, however, name the inverse sibling (cavalry_connect) to sharpen the contrast.

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 when-to-use, when-not-to-use, or alternative is given in the description. The only guidance in the whole definition lives in the schema ('Use cavalry_list_layers to find ids'), and nothing tells the agent how this differs from rewiring via cavalry_connect or inspecting via cavalry_inspect_connections.

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=false, idempotentHint=false, destructiveHint=false, so the agent knows this is a non-destructive, non-idempotent mutation. The description adds the return value (ids of new layers), which is useful but limited; it doesn't mention side effects, permissions, or state changes beyond the 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?

Two short sentences with no waste, front-loading the action and the return value immediately.

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 two-parameter mutation tool with no output schema, the description covers the action and return value. However, it omits context on how the duplication behaves (e.g., does it duplicate children? input connections are optional) and lacks usage guidance, leaving gaps for an agent operating in a rich sibling ecosystem.

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 both parameters (layerId, withInputConnections) are fully documented in the schema, including an example and a cross-reference to cavalry_list_layers. The description adds no parameter details beyond the schema 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 (duplicate) and resource (layer), and notes it returns ids of new layers. It is distinct from siblings like cavalry_create_layer or cavalry_rename_layer, though it doesn't explicitly name an alternative duplication tool.

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 on when to use this tool versus alternatives such as cavalry_create_layer or how it fits in a duplication workflow. The agent must infer context from the name alone.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered without the description. The description adds the batch-read fact ('one or more attributes'), but says nothing about error behavior for invalid attribute paths or missing layers, nor about the shape of returned data.

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

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

A single sentence with zero filler, front-loading the action and scope. Nothing needs to be trimmed and nothing redundant is restated from 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?

For a two-parameter read tool with annotations covering safety, this is nearly complete. The gap is the absence of any output schema and no description of the return shape (e.g., ordered values vs. keyed map matching attrIds), which the description should supply when no output schema exists.

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 50% and, while both parameters carry inline descriptions (attrIds documents path syntax like 'position.x', layerId points to cavalry_list_layers), the description only restates that it is 'one or more attributes on a layer'. It adds essentially no semantics beyond the schema, so a baseline 3 is appropriate.

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

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

The description states a specific verb ('Read') and resource ('current values of one or more attributes on a layer'), so the agent immediately knows this is a batch read of attribute values. It does not, however, differentiate itself from the sibling cavalry_list_attributes, which is the most likely point of confusion.

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 only implied: 'current values' signals a read/state-inspection operation, and 'one or more attributes on a layer' hints at bulk reads. There is no explicit when-to-use, no mention of prerequisites (a valid layerId), and no routing away from cavalry_list_attributes or cavalry_get_bounding_box.

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 openWorldHint=false, so the non-mutating, local-only profile is covered. The description adds the set of returned measurements, which is useful context, but says nothing about coordinate space behavior beyond the schema or about how the box is computed.

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, zero waste, with the return contents front-loaded before the use case. 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?

With no output schema, the description usefully enumerates the returned fields, which is the key piece an agent needs. It leaves the world vs. local coordinate behavior to the schema's worldSpace parameter, a minor gap for an otherwise simple two-parameter read tool.

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

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

Schema description coverage is 100%, so both parameters (layerId with example id and pointer to cavalry_list_layers, and worldSpace with its default) are fully documented in the schema. The description adds no meaning beyond that, 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 ("Return") and resource ("a layer's bounding box") and enumerates the exact components returned (x, y, width, height, centre, left/right/top/bottom). No sibling tool returns a bounding box, so an agent can route to it unambiguously 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?

Gives clear intended contexts: laying out, aligning, and checking that layers fit inside the composition. It does not name an alternative tool or state when not to use it, so it stops short of full when/when-not 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the useful behavioral detail that results come back in hierarchy order, but says nothing about what happens when nothing is selected or how large the response can get.

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 sentence with no filler, front-loaded with the verb and resource and ending with the ordering qualifier. 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?

For a zero-parameter read tool this is close to adequate, but with no output schema the description is the only place return shape could be described, and it gives only ordering — not what each returned layer contains (id, name, type) or the empty-selection case.

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 no parameter semantics to document; the baseline of 4 applies. Schema coverage is 100% on an empty object, so nothing is missing.

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 ('Return') plus resource ('the layers currently selected in Cavalry') and even a scope/ordering detail ('in hierarchy order'). It is clearly distinct from cavalry_select (which sets selection) and cavalry_list_layers (which returns all layers) by implication, but it never names those siblings 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?

No statement of when to use this versus cavalry_list_layers or cavalry_select, and no prerequisites (e.g. whether a scene must be open, what happens with an empty selection). The agent must infer usage entirely from the name and description.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered without the description. The description adds useful scope detail (both incoming and outgoing edges) but says nothing about return structure, ordering, or volume, which is the remaining gap for a read/inspect 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?

A single front-loaded sentence with the action first and the motivation second; every word carries information and nothing is padded.

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 is low complexity with one fully documented parameter, so the description is nearly sufficient. It is incomplete in that there is no output schema and the description never indicates what the connection listing looks like, leaving the agent to discover the response shape empirically.

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 parameter with 100% schema description coverage, including an example id format and a pointer to cavalry_list_layers to obtain ids. The description adds no parameter meaning beyond that, 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 ("List") and resource ("a layer's incoming and outgoing attribute connections") with the direction scope made explicit, which an agent can act on immediately. It does not differentiate itself from the closely related siblings cavalry_connect / cavalry_disconnect, so it stops short of a 5.

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

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

The trailing clause "to understand an existing node graph" implies the inspection use case, which is genuine guidance. However, there is no explicit when-to-use vs when-not, and no routing to cavalry_connect / cavalry_disconnect for the mutation counterparts an agent would likely consider next.

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 openWorldHint=false, so the safety profile is covered. The description adds only the optional-type detail; it doesn't mention output shape, how many attributes might appear, or any limitations beyond annotations.

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

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

A single, front-loaded sentence with no waste. Could be slightly more helpful with a hint about usage.

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 read-only listing tool with full schema coverage and annotations, the description is adequate but lacks any guidance on when to prefer this over sibling attribute tools or what the output contains.

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 all three parameters are already documented in the schema with defaults and examples. The description restates the includeTypes option but omits includeValues, adding no new semantic detail over the schema. 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 (List) and resource (attribute paths on a layer) and clarifies scope. It is distinguishable from siblings like get_attributes (fetch specific values) but doesn't explicitly contrast with them.

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

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

Implied usage is discovery of attribute paths, but the description doesn't explain when to use this versus cavalry_get_attributes or why one would include types/values here instead of fetching separately.

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 openWorldHint=false, so the safety profile is covered. The description adds real value by disclosing the return shape (id, name, type, parent), which matters because there is no output schema, but it says nothing about ordering, pagination, or behavior when no composition is active.

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 sentence with zero waste, front-loading the action and resource before the scope and return fields. Nothing could be removed without losing 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 zero-required-parameter, read-only listing tool with annotations covering safety and no output schema, the description covers purpose, scope, and return shape adequately. Minor gaps remain around result ordering and behavior outside an active composition, but nothing an agent needs to call it 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?

Schema description coverage is 100%, so both filter parameters (type, topLevel) are fully documented in the schema and the baseline is 3. The description adds nothing about the filtering options, but the schema already carries that burden.

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 (list layers) plus the scope ('in the active composition'), and enumerates the returned fields (id, name, type, parent). It does not name a sibling it is distinct from, so it stops short of a 5, but an agent can tell it apart from delete/rename/select tools 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?

Usage is implied by the scope phrase 'in the active composition' and by the returned identity fields, which suggest a discovery/inspection step before acting on a layer. However, there is no explicit when-to-use guidance and no mention of alternatives such as cavalry_get_selection or cavalry_list_attributes for narrowing results.

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 idempotentHint=false, but the description adds real behavioral context the annotations cannot convey: Cavalry may interactively prompt the user about unsaved changes unless force is true. It stops short of saying what happens to the current scene on success or on file-not-found.

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

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

Two sentences, zero filler, with the core action front-loaded and the conditional force behavior immediately after. Nothing could be removed without losing 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 two-parameter tool with a full-schema description and annotations covering safety, the description supplies the one non-obvious behavior (user prompting around unsaved changes). No output schema exists, but the return is simple enough that this is a minor omission.

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 both parameters are already documented in the schema; the description's mention of force reinforces but does not extend that meaning. Baseline 3 is appropriate when the schema carries the parameter semantics.

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 ('Open a .cv scene file'), which is unambiguous against siblings like cavalry_save_scene and cavalry_scene_info. It does not explicitly name the contrasting sibling, but the file-type qualifier makes the scope 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?

Usage is implied (load a scene file into Cavalry) and the description gives the condition that governs the force parameter, but it never states when to choose this tool over alternatives such as save_scene or scene_info, nor any prerequisite about the current scene being replaced.

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 signal readOnlyHint=true and openWorldHint=false, so the description only needs to add context. It does so by describing both the connectivity check and the version information returned; the only minor gap is that it does not say what a failure looks like.

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?

It is two short sentences with no redundancy, and it front-loads the primary check before mentioning the secondary return values.

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 no-parameter health-check tool with annotations and no output schema, the description covers purpose and return content. It would be a 5 if it mentioned the expected result/status or failure behavior.

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 the baseline is 4. No parameter documentation is needed, and the description does not waste space on it.

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

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

The description states a specific verb ('check') and a specific resource ('Cavalry running and the bridge reachable'), and it also names what the tool returns (bridge and Cavalry versions). This makes it clearly distinguishable from the many mutation and scene-inspection siblings, none of which are health checks.

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 makes it obvious that this is a pre-flight connectivity check, so an agent can infer calling it before other cavalry_* operations. It does not, however, explicitly say when not to use it or name an alternative, 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 readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds only the viewport scope, without explaining what stopping does to the playhead or whether playback affects scene state.

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 sentence with no wasted words, front-loading the core action and scope.

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 trivial play/stop tool with annotation-covered safety and a self-documenting enum, the description is nearly complete. It could clarify the playhead behavior on stop, but no output schema exists and the parameter is obvious.

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%, but the single 'action' parameter has a self-explanatory enum of 'play' and 'stop'. The description's phrase 'Start or stop' reinforces the enum but adds no syntax or behavioral detail beyond it.

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

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

The description states a specific verb (start/stop) and resource (playback) with scope (in the viewport). It does not explicitly differentiate from any sibling tool, such as cavalry_set_frame, which also affects the 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?

There is no explicit when-to-use or when-not-to-use guidance. The description implies usage from the actions but offers no alternatives 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 declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety and repeatability profile is covered. The description's 'display name' wording adds a small clarification that this does not alter the layer id, but discloses nothing about permissions, failure modes, or return behavior.

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

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

A single short sentence with no wasted words and the core operation front-loaded. It is efficient, though arguably under-specified rather than deliberately concise.

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 two-parameter mutation with no output schema and annotations covering the safety profile, the definition is minimally adequate. The schema supplies the id lookup hint, but the description contributes nothing further about validation, naming constraints, or the result of the rename.

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 only 50%: layerId is documented in the schema (with a pointer to cavalry_list_layers), but the 'name' parameter has no description. The tool description adds no parameter meaning at all, so it fails to compensate for the coverage gap.

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 ('Change') and resource ('a layer's display name'), making the operation unambiguous. It does not differentiate itself from potential siblings that could also affect layer naming, such as cavalry_set_attributes, so sibling differentiation is absent.

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 when-to-use guidance, no prerequisites, and no mention of alternatives. An agent cannot tell from the description whether cavalry_set_attributes could also rename a layer or when this tool should be preferred.

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=false, destructiveHint=false, and non-idempotent, so the agent knows this is a write-like operation. The description adds that it writes a file to the local machine, which is useful context, but says nothing about overwrite behavior, blocking/duration, or rate limits for large renders.

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 with the core action and output location front-loaded, then the practical path constraint. Every clause earns its place with 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?

Adequate for a single-output render tool: the action, destination, and path format are covered. With no output schema, it could say what is returned (e.g., path or success) or whether an existing file is overwritten, but the description is otherwise sufficient to call 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 already documents all three parameters, including the path and extension behavior. The description largely restates 'absolute path' and the auto-appended .png extension rather than adding syntax or format meaning beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb (Render) and resource (the active composition to a PNG file), plus the scope (active composition, local machine). No sibling tool performs rendering, so it is unambiguously distinguishable from the layer/attribute/keyframe manipulation tools around it.

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 parenthetical '(useful for checking your work visually)' implies a usage context, but there is no explicit when-to-use/when-not, no prerequisites, and no named alternative. Usage is only implied, which matches the 3 baseline.

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, idempotentHint=true, destructiveHint=false, openWorldHint=false), so the description only needs to add context. It clarifies the mode switch, which is useful, but says nothing about overwrite behavior, failure modes, or unsaved-changes implications. It does not contradict the 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?

One sentence, no filler, and the mode condition is front-loaded. 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?

For a one-parameter tool with no output schema, the description covers what an agent must decide (in-place vs new path) and does not need to explain return values. It leaves overwrite/error semantics unstated, which is 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?

There is a single optional parameter and schema description coverage is 100% — the schema already states "Absolute .cv path for Save As. Omit to save in place." The description restates the same conditional without adding format or edge-case detail, 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?

The description names a specific verb and resource (save the scene) and distinguishes the two operating modes: in-place save versus Save As when filePath is supplied. It is unambiguous, though it never names the natural counterpart, cavalry_open_scene, 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?

It gives a clear conditional: provide filePath for a new .cv path, omit it to overwrite the current file. That is enough for an agent to choose the right mode, but there is no guidance on when to prefer Save As over in-place saving, or what happens on an existing path.

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 openWorldHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the returned fields and the "when available" qualifier, hinting that composition-dependent values may be absent. It does not state the failure mode when no scene is open.

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, front-loaded with the resource and payload followed by the actionable usage instruction. 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?

With no output schema, the description carries the burden of describing returns, and it does enumerate the primary fields. The "when available" hedge leaves some ambiguity about the exact response shape, but for a zero-parameter read tool this is largely 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 tool takes zero parameters, so the baseline is 4. Nothing in the description needs to compensate for parameter documentation, and it introduces no misleading parameter hints.

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 ("Describe") and resource ("the open scene") and enumerates the exact payload: file path, unsaved state, current frame, compositions, resolution/frame range/fps. This clearly separates it from siblings like cavalry_open_scene, cavalry_save_scene, and cavalry_get_selection.

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?

"Call this first to orient yourself" gives explicit sequencing guidance, which is genuinely useful for an agent starting a session. It stops short of naming alternatives or when-not-to-use conditions, so it is not a full 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?

The annotations already declare the mutation profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the safety bar is lower. The description's one added fact, that the existing selection is replaced rather than extended, is genuinely useful and consistent with the annotations, but nothing is said about invalid layer ids, empty/scene-missing cases, or the effect on existing selection state.

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 front-loaded sentence with the mutated state ('current selection') and the input ('given layers') stated immediately; nothing is wasted or 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?

For a one-parameter state-mutation tool with a fully documented schema and annotations covering the safety profile, the description covers the essential replace semantics. Minor gaps remain around invalid-id handling and scene preconditions, but no output schema is needed here.

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 'layerIds' parameter is already documented in the schema as 'One or more Cavalry layer ids.' The description adds no format, id-source, or ordering detail beyond that, 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 (select/replace) and resource (selection of layers) with the scope qualifier 'replace the current selection.' An agent can distinguish it from the read-oriented cavalry_get_selection by the replace semantics, though no sibling is named 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?

No guidance on when to use this tool, no prerequisites (e.g., a scene must be open), and no mention of alternatives such as cavalry_get_selection for reading the current selection or cavalry_list_layers for discovering valid ids.

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, idempotentHint=true, destructiveHint=false, openWorldHint=false). The description adds real behavior the annotations cannot convey: that all attribute paths are validated up front because Cavalry silently ignores writes to unknown paths, which also explains why skipValidation exists.

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, each load-bearing: scope and frame behavior first, then the validation rule, then the rotation tip. No filler and the most decision-relevant fact is front-loaded.

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

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

For a mutation tool with annotations covering safety and a fully documented schema, this is nearly complete. Remaining ambiguity is whether provided attributes merge with or replace existing values and what the call returns, but with no output schema and strong annotation coverage those are minor 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 description coverage is 100%, so the baseline is 3. The description still adds meaning beyond the schema by explaining the pre-write path check (the reason skipValidation exists) and by giving the rotation.z convention for 2D rotation, which the schema's example only shows as a bare value.

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

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

States a specific verb (set) and resource (attribute values on a layer), plus the crucial scope qualifier "at the current frame (does not create keyframes)" that separates it from cavalry_set_keyframes and from the read-side siblings cavalry_get_attributes/cavalry_list_attributes.

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 parenthetical "does not create keyframes" tells the agent when NOT to use this tool and implicitly routes animation writes to cavalry_set_keyframes, and "In 2D, rotate with rotation.z" gives a concrete usage rule. It stops short of naming the alternative tool explicitly or stating prerequisites.

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=false, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds one genuinely useful behavior beyond them: an empty string clears the expression rather than setting it. It does not disclose what happens to an existing expression, whether errors surface, or permission requirements.

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 front-loaded sentence with no filler and the primary operation stated first, followed by the clear-semantics in parentheses. It is efficient, though arguably terse for a mutation tool with three required parameters.

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 and an existing annotation set, the description covers the essentials but leaves gaps an agent would care about for a write tool: whether an expression replaces an existing one, how expression errors are reported, and whether the attribute must already exist. Adequate but not 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?

Schema coverage is 67%: attrId and layerId are documented (the latter pointing to cavalry_list_layers), but the required 'expression' parameter has no schema description. The description compensates by establishing that the value is a JavaScript expression and that an empty string clears it, which is meaning the schema alone does not provide.

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 (Set) and resource (a JavaScript expression on an attribute), with a clear secondary operation (clear via empty string). It is distinguishable from cavalry_set_attributes and cavalry_add_dynamic_attribute by acting on expressions specifically, though it never names a sibling to sharpen the boundary.

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 documents the empty-string clearing trick, which is a usage rule, but gives no when-to-use versus alternatives such as cavalry_set_attributes, cavalry_add_dynamic_attribute, or cavalry_connect. No prerequisites (e.g., needing a layer id from cavalry_list_layers) are stated even though the schema hints at 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?

Annotations already declare the behavioral profile (idempotentHint=true, destructiveHint=false, readOnlyHint=false), so the safety story is covered and consistent with 'move the playhead'. The description adds useful scope context — it acts on the *active* composition — but says nothing about out-of-range frames, clamping, or whether a paused state is required.

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 front-loaded sentence with zero filler; the verb and target are stated before any qualifiers. Nothing extraneous to trim.

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 state-setting tool with no output schema, the description covers what is needed to invoke it correctly. It could mention frame-range behavior or whether the composition must be open, which is the only remaining 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?

Only one parameter and schema coverage is 100%, so 'Target frame number' is already in the schema. The description adds no format, range, or unit guidance beyond that, making this the baseline 3 case where the schema does the heavy lifting.

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

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

States a specific verb and object ('Move the playhead') plus the scope ('active composition') and the value being set ('a frame'). An agent immediately knows this is playhead navigation, distinct from mutation siblings like cavalry_set_keyframes. It loses the top mark only because it doesn't explicitly distinguish itself from the neighboring cavalry_playback tool.

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 its usage (jump the playhead to a specific frame) but offers no explicit when-to-use statement, no prerequisites, and no routing against alternatives such as cavalry_playback. Adequate but leaves the agent to infer context.

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

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

Annotations already declare the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=false), and "swap" is consistent with a non-destructive, idempotent mutation. Beyond that the description adds little: it does not say what happens to an existing generator, whether invalid type ids error, or what the call returns.

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 front-loaded sentence with zero filler, and the illustrative examples are placed where they are most useful. Minor redundancy between "swap" and "set" keeps it short of perfect.

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 3-param idempotent setter with full schema coverage and no output schema, the description is adequate but thin: it omits error behavior for unknown generator ids and any hint about reusing the layer's existing generator/attribute slot.

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 layerId and type are already documented in the schema; baseline is 3. The description's value examples reinforce the type parameter but add no semantics beyond the schema, and it says nothing about attrId.

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 ("swap"/"set") and resource (the generator on a layer), plus concrete examples ("circleDistribution", "ellipse") that make the intent unmistakable. It does not, however, distinguish this specialized setter from the sibling cavalry_set_attributes, leaving the agent to infer the boundary.

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 through the examples (a Duplicator's generator vs a Basic Shape's generator), which hints at applicable layer types, but there is no explicit when-to-use / when-not-to-use guidance and no mention of cavalry_set_attributes as the general alternative.

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 declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, so safety profile is covered. Description adds the Magic Easing concept and example structure, but doesn't clarify what happens on frames that already have keyframes (overwrite? append?) or permission requirements.

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-loaded with the core action, then a concrete example. Efficient but the example is long; still, it earns its place by clarifying structure.

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 mutation tool with annotations covering safety, the description is adequate but missing: behavior on existing keyframes, return format, and how it interacts with cavalry_set_attributes. No output schema to offload return details, so the description could say more about what's returned.

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 50%. The example clarifies the shape of the values map and easing application, which is helpful. However, the 'expression' property is not explained in the description, leaving half the nested parameter semantics to the schema alone.

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 (Create) and resource (keyframes on a layer). Clear what it does, but doesn't explicitly differentiate from the sibling cavalry_delete_keyframes or cavalry_set_attributes.

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?

Implied usage by describing keyframe structure, but no explicit when-to-use vs cavalry_set_attributes or cavalry_delete_keyframes. An agent might wonder whether to set keyframes here or attributes elsewhere.

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 as a non-read-only, idempotent, non-destructive mutation, so the safety profile is covered. The description's added behavioral detail (null parentId moves the layer to the top level) largely duplicates the parentId schema description, and it says nothing about transform/world-position handling or cycle rejection.

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 tight sentence that front-loads the primary action and appends the alternative mode without wasted words.

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

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

For a two-parameter, non-destructive mutation with full schema coverage and annotations but no output schema, the description is nearly sufficient. It could still note error conditions (invalid id, circular parenting) or whether the call returns anything, but nothing critical for invocation 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?

Schema description coverage is 100%, so both parameters are already documented, including the null-to-top-level semantics and a pointer to cavalry_list_layers for ids. The description adds no syntax or format detail 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?

States a specific verb and resource — parenting a layer under another layer — and even names the common target type (a group). It is clear what the tool does, but it never explicitly contrasts itself with neighboring tools such as cavalry_connect or cavalry_duplicate_layer, which also alter scene hierarchy relationships.

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 covers both operational modes: parenting under an existing layer and passing null to un-parent. This gives clear context for when each invocation style applies, though it offers no exclusions or caveats (e.g. cycles, cross-scene parents) and never names an alternative tool.

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