Server Quality Checklist

Tool Scores

• motion_unpublish_parameterC
  2.8/5.0
  Behavior2/5

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

  With no annotations, the description carries the full burden of behavioral disclosure. It only states the bare operation, omitting side effects, failure conditions, permissions, or what happens to associated data. For a mutation tool, this is insufficient.

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

  Conciseness4/5

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

  A single concise sentence with no wasted words, front-loading the core action. However, the extreme brevity edges toward under-specification, lacking structure for a tool with three required parameters.

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

  Completeness2/5

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

  Given the tool's complexity (3 required params, no annotations, no parameter semantics), the description is incomplete. An output schema exists, which helps, but the description still needs to explain the operation's context, side effects, and parameter roles.

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

  Parameters1/5

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

  The schema covers 0% of parameters, and the description provides no explanations for 'path', 'channel', or 'object_id'. There is no indication of what values are expected or how they identify the parameter to unpublish.

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

  Purpose5/5

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

  The description uses a specific verb ('Remove') and resource ('published (rig) parameter'), clearly stating the tool's function. It distinguishes itself from sibling 'motion_publish_parameter' which does the opposite.

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

  Usage Guidelines2/5

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

  No guidance is provided on when to use this tool versus alternatives, nor any prerequisites. The description implies usage for unpublishing a parameter but offers no explicit context or exclusions.

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

• motion_list_layersB
  3.3/5.0
  Behavior3/5

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

  With no annotations, the description carries the burden of behavioral disclosure. It details the output contents, which is useful, but does not explicitly state that the operation is read-only, has no side effects, or requires an open template. The verb 'List' suggests safety but is not explicit.

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

  Conciseness5/5

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

  The description is a single, well-structured sentence that front-loads the action and resource, then lists the output fields. Every word contributes information with no redundancy or filler.

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

  Completeness2/5

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

  While the output schema likely covers return values, the description omits any explanation of the input parameter 'path' and lacks usage guidance. For a tool with a single undocumented parameter, the description should at least hint at what the path refers to, which it does not.

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

  Parameters1/5

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

  The input schema has a single 'path' parameter with no description, and the tool description does not explain what 'path' refers to (template file path, layer path, etc.). This is a critical gap especially since schema description coverage is 0%, leaving the user to guess.

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

  Purpose5/5

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

  The description clearly states the action (List), the resource (every layer in the template's layer tree), and the specific fields returned (id, name, factory kind, nesting depth, locked). It distinguishes itself from the sibling motion_list_text_layers by specifying 'every layer' rather than only text layers.

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

  Usage Guidelines3/5

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

  The description implies the tool is for obtaining a complete layer list, but it does not explicitly mention when to use it versus alternatives like motion_list_text_layers. No exclusion or conditional guidance is provided, though the sibling name provides a subtle hint.

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

• motion_list_text_layersB
  3.3/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full burden. It discloses that the tool lists text layers and returns their string and scenenode id, which suggests a read-only operation, but it does not mention prerequisites, error handling, or side effects. The added value is limited to the output fields.

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

  Conciseness5/5

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

  The description is a single concise, front-loaded sentence that clearly states the action and result with no filler. Every word adds value, making it appropriately sized for a simple list operation.

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

  Completeness2/5

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

  Although the tool has an output schema and is a low-complexity list operation, the required `path` parameter is completely unexplained, leaving a significant gap in usage context. The description does not clarify the nature of the path or how it relates to the tool's siblings, making it incomplete for practical invocation.

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

  Parameters1/5

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

  The schema has one required parameter `path` with no description, and the tool description does not mention `path` at all. With 0% schema description coverage, the description fails to compensate by explaining what the parameter means or how to provide it, leaving the agent without essential information.

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

  Purpose5/5

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

  The description uses a specific verb 'List' and identifies the exact resource 'Text-factory layer', while specifying the output fields (current on-screen string, scenenode id). It clearly distinguishes itself from the sibling `motion_list_layers` by focusing on text layers and explicitly notes the output is 'needed by motion_set_text'.

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

  Usage Guidelines3/5

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

  The description implies usage when you need text layer info for motion_set_text, but it does not explicitly state when not to use this tool versus `motion_list_layers` or other alternatives. There is no direct comparison or exclusion criteria, so the guidance remains implicit.

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

• motion_set_colorB
  3.4/5.0
  Behavior3/5

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

  With no annotations, the description carries the transparency burden. It discloses the value range (0.0-1.0, with >1.0 allowed for over-bright colors), which is useful. However, it does not mention side effects, alpha behavior, or error conditions, leaving most behavioral aspects undisclosed.

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

  Conciseness4/5

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

  The description is concise at two sentences, but the first sentence is long and packs the example into a parenthetical, making it slightly dense. Still, it is efficient and free of fluff.

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

  Completeness2/5

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

  The tool has 7 parameters and no annotations, and the description leaves key details unexplained (e.g., path vs parameter_path, alpha semantics). The output schema may help with return values, but it cannot compensate for missing parameter semantics and usage context.

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

  Parameters2/5

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

  Schema description coverage is 0%, so the description must compensate. It clarifies color values and gives a parameter_path example, but does not explain the distinction between 'path' and 'parameter_path', nor the meaning of 'scenenode_id' or the optional alpha. This is insufficient for a 7-parameter tool.

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

  Purpose5/5

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

  The description clearly states the tool's function: 'Set RGB(A) on a color parameter group' with a concrete example ('Style/Face/Color'). This distinguishes it from siblings like motion_set_parameter_value, which is generic.

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

  Usage Guidelines3/5

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

  The description implies use for color parameter groups via the example, but it does not explicitly state when to use this tool versus alternatives like motion_set_parameter_value. There is no exclusion or alternative naming, so usage guidance is implied rather than explicit.

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

• motion_list_rigA
  3.6/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the behavioral transparency burden. It states this is a listing operation, implying no side effects, but does not explicitly state read-only behavior, error conditions, or path requirements. It adds useful context about what 'rig' means in FCP terms.

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

  Conciseness5/5

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

  The description is a single sentence with a clear, efficient explanation, including a helpful parenthetical defining 'rig'. No wasted words.

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

  Completeness3/5

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

  The description covers the tool's purpose well and benefits from having an output schema, reducing the need to explain return values. However, it leaves the 'path' parameter undefined and does not mention any prerequisites or side effects. Overall, it's adequate but has notable gaps given no annotations.

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

  Parameters2/5

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

  The input schema has one required parameter 'path' with no description, and the description does not explain what 'path' refers to. There is zero schema description coverage, and the description fails to compensate. Only from the tool's context can one infer 'path' likely points to the template file.

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

  Purpose5/5

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

  The description uses the specific verb 'List' with a clear object 'every published (rig) parameter', and elaborates that these are the controls FCP's Inspector shows. This clearly distinguishes it from sibling tools like motion_get_parameter (single parameter) and motion_list_layers (layers).

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

  Usage Guidelines3/5

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

  The description clearly states what the tool does but does not explicitly mention when to use it versus alternatives. There is no guidance on exclusions or when to prefer a different tool, such as motion_get_parameter for individual parameters. The context is implied by the tool's focus on published/rig parameters.

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

• motion_publish_parameterA
  3.7/5.0
  Behavior3/5

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

  With no annotations provided, the description must carry the full behavioral disclosure burden. It explains that this publishes a parameter and where it becomes visible, and it clarifies the provenance of object_id and channel. However, it does not mention side effects, whether a project must be open, or what happens on invalid inputs. It gives useful context but not complete behavioral transparency.

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

  Conciseness4/5

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

  The description is only two sentences and front-loads the primary purpose before the technical example. It is efficient and every sentence contributes useful information, though the example adds some complexity that could be formatted more cleanly.

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

  Completeness3/5

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

  The description provides a clear purpose, a concrete example, and a discovery strategy for object_id and channel. However, it lacks definitions for the path and name parameters, does not describe the return value or error behavior, and offers no guidance on prerequisites like having a Motion template open. It is adequate but incomplete.

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

  Parameters2/5

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

  The schema description coverage is 0%, so the description must explain parameters. It offers a concrete example for object_id and channel, but it entirely omits descriptions for 'path' and 'name', which are also required. This leaves half the parameters undefined and requires the agent to guess or infer their meaning.

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

  Purpose5/5

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

  The description specifies a concrete action ('Publish an internal parameter as a rig control') and names the exact context (Final Cut Pro's Inspector) and resource (internal parameter). It clearly distinguishes this from sibling operations like motion_unpublish_parameter or motion_list_rig.

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

  Usage Guidelines4/5

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

  The description gives explicit context for when to use the tool (to expose a rig control) and provides a practical method for discovering the correct object_id and channel values via motion_list_rig. It does not explicitly state when not to use it or mention alternatives, but the guidance is strong and actionable.

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

• motion_set_textA
  3.7/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full transparency burden. It discloses that only the text content changes and that font, color, and behaviors remain untouched, which is a key behavioral guarantee. However, it does not mention potential side effects, error conditions, or whether the change is persistent.

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

  Conciseness5/5

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

  The description is a single, tightly constructed sentence that delivers the essential information first and adds a clarifying clause. Every word earns its place without unnecessary elaboration.

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

  Completeness2/5

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

  While the description explains the core operation, it omits crucial contextual details such as how to specify the target layer (path vs. scenode_id), any prerequisites beyond being a Text-factory layer, and behavior on invalid input. The presence of an output schema mitigates the need to describe return values, but for a 3-parameter tool with no schema descriptions, more guidance is needed.

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

  Parameters2/5

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

  The input schema has 0% description coverage, so the description must compensate, but it does not. It only hints that new_text is the new string ('on-screen string'), while path and scenode_id are left entirely unexplained, which could confuse an agent unfamiliar with the domain.

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

  Purpose5/5

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

  The description clearly states the primary action: 'Change the on-screen string of a Text-factory layer.' It uses a specific verb and resource, and explicitly distinguishes its scope by noting font, color, and behaviors are untouched. This differentiates it from sibling tools like motion_set_color.

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

  Usage Guidelines4/5

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

  The description implies the appropriate use case: when you need to alter only the text content of a Text-factory layer, leaving all other attributes intact. It provides clear context by listing what it does not affect, though it does not explicitly name alternative tools for those other attributes.

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

• motion_list_keyframesA
  3.8/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the burden. The word 'List' implies a read-only operation, and the description discloses ordering and return fields (time, value). However, it doesn't explicitly guarantee non-mutation, discuss edge cases (e.g., missing parameter), or mention performance for large curves.

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

  Conciseness5/5

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

  The description is a single, front-loaded sentence that conveys purpose, output format, and ordering without wasted words. Every word earns its place.

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

  Completeness3/5

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

  The description adequately covers the tool's purpose and output aspects, and the existence of an output schema covers return values. However, the complete lack of parameter semantics and usage guidance for a 3-parameter tool leaves notable gaps.

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

  Parameters2/5

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

  Schema description coverage is 0% and the description does not define any of the three parameters (path, scenenode_id, parameter_path). While the context implies parameter_path refers to the animated parameter, the description offers no explicit meaning for any parameter, leaving the agent to infer.

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

  Purpose5/5

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

  The description clearly states the action ('List'), the resource ('keypoints on an animated parameter's curve'), and the scope ('every keypoint... in document order, with time (seconds) and value'). This distinguishes it from sibling tools like motion_list_layers and motion_list_text_layers, which list different resources.

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

  Usage Guidelines4/5

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

  The description implies when to use this tool: when you need to see all keyframes on an animated parameter. However, it doesn't explicitly mention alternatives or specify when not to use it, so it stops short of full exclusion guidance.

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

• motion_save_asA
  3.8/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden and discloses the key safety behavior: 'Never overwrites the originally-opened file unless output_path is the same path.' It also clarifies the consequence of passing a new filename (keeps source untouched). It does not state whether an existing output file will be overwritten, but 'Write' implies this; still, this 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.

  Conciseness5/5

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

  The description is two sentences, front-loaded with the primary action ('Write'), and every phrase earns its place. It includes a crucial safety qualifier without unnecessary elaboration.

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

  Completeness3/5

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

  For a simple file-save tool, the description covers the essential behavior and the most important safety condition. However, the missing explanation of the 'path' parameter is a significant gap that could lead to incorrect invocation. The presence of an output schema mitigates the need to describe return values, but parameter semantics remain incomplete.

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

  Parameters2/5

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

  The input schema has 0% description coverage, so the description must compensate. It explicitly explains output_path ('where the document is written') but does not explain the 'path' parameter at all. The phrase 'open, modified document' hints that 'path' identifies the source, but this is not explicit, leaving the agent to guess the role of a required parameter.

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

  Purpose5/5

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

  The description uses a specific verb ('Write') and resource ('the open, modified document to output_path'), clearly stating the save-as functionality. It distinguishes itself from sibling tools which are focused on listing, opening, setting, and keyframing, none of which perform save operations.

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

  Usage Guidelines3/5

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

  The description implies usage by stating 'pass a new filename to keep the source template untouched,' giving a clear use case for when a new output path is desired. However, it does not explicitly state when to use this tool versus any alternative, nor does it mention any exclusions or prerequisites beyond the implied 'open, modified document' condition.

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

• motion_open_in_motionA
  3.9/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the transparency burden. It discloses the server's limitations (cannot render frames or drive UI), but does not explain side effects like launching Motion, blocking behavior, or environment requirements. This is partial but not comprehensive.

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

  Conciseness5/5

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

  The description is a single, front-loaded sentence with clear purpose and a succinct explanation of the tool's role. It contains no fluff and every clause contributes to the understanding.

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

  Completeness4/5

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

  For a simple one-parameter tool, the description covers the purpose and workflow context well. The existence of an output schema means return values need not be described. Minor gaps include not stating prerequisites like Motion.app being installed, but the overall picture is clear.

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

  Parameters2/5

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

  The only parameter, path, has no schema description (0% coverage). The tool description does not add any details about the path format, absoluteness, or constraints. It only implies that a file is opened, leaving the parameter semantics largely undefined.

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

  Purpose5/5

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

  The description states a specific verb+resource: "Open a file in Motion.app for visual review." It also distinguishes itself from sibling tools by explaining that the server cannot render frames or drive Motion's UI, making this the designated way for visual QC.

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

  Usage Guidelines4/5

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

  The description provides clear context: "final visual QC always happens by handing the file to the app this way," indicating when this tool should be used. However, it does not explicitly name alternatives or state when not to use it, so it falls short of a 5.

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

• motion_add_keyframeA
  4/5.0
  Behavior3/5

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

  With no annotations, the description carries the burden of disclosing behavior. It clearly indicates the append operation and the existing-curve prerequisite, but does not describe potential errors when the precondition is violated, nor the effect of the optional interpolation parameter. It provides some useful context but lacks full behavioral disclosure for a mutating tool.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the primary action, and uses the second sentence to provide a critical workflow alternative. Every word earns its place; no redundancy or filler.

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

  Completeness3/5

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

  The description effectively captures the tool's core purpose and its relationship to a sibling tool, which is especially important given no annotations. However, it omits important operational details like parameter format/encoding, interpolation behavior, and failure modes. Given the tool's moderate complexity and six parameters, this is only partially complete.

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

  Parameters2/5

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

  Schema description coverage is 0%, so the description must compensate for parameter meaning. It does not explain any of the six parameters individually, such as the format of 'path', 'parameter_path', 'value', or how 'interpolation' affects the keypoint. While the names and context hint at semantics, the description adds no concrete parameter-level guidance.

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

  Purpose5/5

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

  The description uses a specific verb ('Append a keypoint') and identifies the resource ('a parameter that is ALREADY keyframed in Motion'), clearly differentiating from the sibling tool motion_create_keyframe_curve. It also specifies the precondition of an existing curve, making the tool's purpose unmistakable.

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

  Usage Guidelines5/5

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

  The description explicitly states when to use the tool (append to an already-keyframed parameter) and when not to use it (if never keyframed), directing the agent to call motion_create_keyframe_curve first. This is exemplary guidance for tool selection.

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

• motion_get_parameterA
  4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden. It discloses the read-only nature via 'Inspect' and details the return values, including the distinction between leaf and group parameters. It does not explicitly state 'does not modify', but the language strongly implies a non-mutating operation and explains what to expect.

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

  Conciseness5/5

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

  The description is concise: two sentences, no fluff. The first sentence defines the action and gives examples, the second lists the return info. Every word earns its place.

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

  Completeness3/5

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

  With an output schema present, the description doesn't need to detail return types, and it does explain the semantic content of the output. However, the parameter ambiguity is a significant gap for a 3-parameter tool with no schema documentation. The description is complete in purpose but incomplete in parameter guidance, making it only minimally complete overall.

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

  Parameters2/5

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

  Schema has 0% coverage, so the description must compensate. It provides path format examples ('Object/Text' or 'Style/Face/Color/Red') and explains the concept of a slash-separated path, but it fails to map these to the schema's three parameters, especially the confusing presence of both 'path' and 'parameter_path'. The examples could apply to either, leaving the agent uncertain about which parameter to fill.

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

  Purpose5/5

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

  The description clearly states the tool's function: 'Inspect a parameter by slash-separated name path from a scenenode' and specifies the exact information returned (value/default, keyframed status, child parameter names). This clearly distinguishes it from sibling tools like motion_set_parameter_value, which modifies parameters.

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

  Usage Guidelines4/5

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

  The description implies usage context: use when you need to inspect a parameter's current state ('Returns its current value/default, whether it's keyframed, and child parameter names'). It does not explicitly name alternatives or state when not to use it, but the read-only 'Inspect' wording naturally contrasts with set/modify siblings.

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

• motion_openA
  4/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses the indexing action, the prerequisite, and the return summary, which is useful. However, it does not mention potential side effects such as whether the file is locked, whether the operation is read-only, or behavior if the file is already open.

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

  Conciseness5/5

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

  The description is two concise sentences, each adding value: the first states the action and resource, the second explains the prerequisite and the return summary. It is front-loaded and contains no extraneous information.

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

  Completeness4/5

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

  The description covers the purpose, the prerequisite, and the return summary. Given the simple one-parameter open/index operation and the presence of an output schema, this is fairly complete. It could add a note about state lifecycle (e.g., that the file stays open until closed with motion_save_as), but it's not a critical gap.

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

  Parameters3/5

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

  The schema has a single path parameter with 0% description coverage, and the tool description doesn't explicitly explain the parameter. However, mentioning specific file types (.motn/.moti) implies the path should point to such a file. For a single obvious parameter, this is adequate, though the description could have directly stated 'path'.

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

  Purpose5/5

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

  The description uses a specific verb phrase 'Open and index' with the resource '.motn or .moti file', clearly stating the tool's primary action. It also establishes the tool's unique role as the mandatory first step with 'Required before any other tool can operate on it', effectively distinguishing it from siblings like motion_open_in_motion.

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

  Usage Guidelines4/5

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

  The description explicitly states a use condition: 'Required before any other tool can operate on it', which tells the agent when this tool must be called. It doesn't name alternative tools or exclusion scenarios, but the prerequisite provides clear contextual guidance.

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

• motion_validateA
  4/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the full burden. It discloses that the file is re-parsed fresh from disk and validated, implying a read-only operation. However, it does not explicitly state side-effects (or lack thereof), error behavior, or permission requirements, leaving some ambiguity.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the primary purpose and followed by a practical use case. Every sentence adds value with no redundancy or filler.

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

  Completeness4/5

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

  Given the tool's simplicity (one parameter, no nested objects) and the presence of an output schema, the description adequately covers the purpose, invocation context, and post-save use case. It lacks explicit return-value details, but the output schema likely provides those.

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

  Parameters3/5

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

  Schema coverage is 0%, but there is only one parameter, 'path'. The description refers to 'a file' read from disk, making it clear the path parameter identifies the target file. It does not add details like path format or required extensions, but the meaning is sufficiently inferable.

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

  Purpose5/5

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

  The description uses a specific verb phrase 'Round-trip-check a file' and clearly states the resource and action: re-parse from disk and confirm the root is a recognizable <ozml> document. This distinctly differentiates it from siblings like motion_open or motion_save_as.

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

  Usage Guidelines4/5

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

  The description explicitly recommends using this tool 'right after motion_save_as to confirm the write didn't corrupt the XML,' providing a clear context. It does not mention exclusions or alternative tools, but the use case is well-defined.

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

• motion_create_keyframe_curveA
  4.5/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden and does well: it discloses that a new curve is created from scratch with one keypoint, that it refuses certain inputs, and how `default` behaves. However, it does not explicitly state that this is a write operation that modifies the document, nor does it mention non-reversibility, so it's not a perfect 5.

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

  Conciseness4/5

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

  The description is long but well-organized and free of fluff. Every sentence adds value: purpose, grounding, constraints, and parameter detail flow logically. It earns a 4 rather than 5 because it could be slightly tighter, but it's still highly readable and efficient.

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

  Completeness4/5

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

  For a 7-parameter tool with no annotations and zero schema coverage, the description covers the core functionality, target parameter type, and key constraints. It leaves out explicit explanations for `path`, `scenenode_id`, and `interpolation`, but the overall context and output schema mitigate those gaps. A 4 is appropriate.

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

  Parameters4/5

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

  Schema coverage is 0%, and the description compensates for key ambiguous parameters: it clarifies `parameter_path` (scalar channel, e.g., 'Style/Face/Color/Red' vs compound) and `default` (overrides rest value or reuses current value). Other parameters like `time_seconds`, `value`, and `interpolation` are not explicitly detailed, but their meaning is inferable from the context.

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

  Purpose5/5

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

  The description clearly states the action: 'Start animating a leaf parameter that has NEVER been keyframed in Motion — creates its curve from scratch, seeded with one keypoint.' It also distinguishes itself from the sibling tool motion_add_keyframe, which is for already-keyframed parameters.

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

  Usage Guidelines5/5

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

  Explicitly specifies when to use this tool (only for never-keyframed leaf parameters) and when not (already keyframed → use motion_add_keyframe; group parameters → refused). It also gives precise targeting guidance by instructing to target scalar channels rather than compound properties.

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

• motion_set_parameter_valueA
  4.6/5.0
  Behavior4/5

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

  No annotations are present, so the description carries full behavioral burden. It discloses a critical safety behavior: refusal to modify keyframed parameters without force=True, and explains the rationale (avoiding silent animation breaks). It does not mention error handling or return behavior, but the output schema covers return values, so this is sufficient.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the primary purpose, and every sentence adds value. The second sentence efficiently conveys a critical exception and an alternative tool without fluff.

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

  Completeness4/5

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

  Given the tool's complexity (5 params, conditional behavior), the description covers the essential context: what the tool does, when to use it, and a key behavioral guardrail. It lacks explicit clarification of all parameter roles (especially the difference between 'path' and 'parameter_path'), but the presence of an output schema mitigates the need to explain return values. Overall, it's complete enough for correct selection and invocation.

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

  Parameters4/5

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

  Schema description coverage is 0%, so the description must add meaning. It explains the core semantic: static value vs keyframed, clarifies the 'force' parameter's default and effect, and provides an example path format. However, it does not explicitly distinguish between 'path' and 'parameter_path', leaving some ambiguity for those parameters.

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

  Purpose5/5

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

  The description clearly states the action ('set a leaf parameter's static value') with a concrete example path. It also distinguishes itself from sibling tools by explicitly pointing to motion_add_keypoint for animated parameters, making the resource and scope unambiguous.

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

  Usage Guidelines5/5

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

  The description provides explicit when-to-use guidance: it refuses keyframed parameters unless force=True, and directly names the alternative tool (motion_add_keypoint) for animated parameters. This gives clear context on when to choose this tool over siblings.

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