HyperCodeMotion MCP

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

Annotations only supply the generic mutation/safety flags (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description carries the real disclosure and does it well: failure returns created:false with errors and stores nothing, success stores the file temporarily, and both open/download links expire after 24 hours. It also discloses that media binaries travel inside the packaged file and are capped, plus the 24-hour lifetime constraint an agent must communicate to the user.

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 the failure path, then output/lifetime, then media — a logical order an agent can parse quickly. The media sentence partially duplicates the schema's own media description, which is the only real waste across three otherwise dense sentences.

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 packaging tool with an output schema, the agent has everything needed to call it correctly: input expectations, success and failure shapes, link lifetime, media capacity constraints, and the explicit non-goal of rendering. The output schema covers return structure, so the description does not need to enumerate fields further.

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 schema already documents json, name and the media item shape, and the description largely restates it ('public https links, or files sent with start_media_upload'). It does add the integration point with the start_media_upload sibling and the layer reference convention, which is genuinely useful cross-tool context. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

States a specific verb+resource pair: 'Validate a finished HyperCodeMotion composition and package it as a .hcmotion project file, the format HyperCodeMotion Studio opens.' This clearly separates it from validate_json (validation only) and start_media_upload (media intake) among the siblings, and the trailing 'It does not render video or generate media' rules out the most likely 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?

The description makes clear this is the terminal step for a finished composition and explicitly excludes rendering/generation, which routes the agent away from a wrong expectation. It also implies the companion workflow by naming start_media_upload for files not yet hosted. It stops short of naming validate_json as a cheaper pre-check, so no explicit alternative is given.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds useful content context such as the contract revision and specific rules/fields, but does not disclose additional behavioral traits like caching, version compatibility handling, or auth requirements beyond what the annotations provide.

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

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

The description is front-loaded with 'List the HyperCodeMotion...', which is good, but it continues as a single long run-on sentence with many comma-separated clauses. Every listed item is relevant, but the structure could be significantly clearer with bullets or shorter sentences.

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

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

Given zero parameters, a rich annotation set, and an existing output schema, the description is largely complete: it states what the tool returns and when to call it. It could be improved by briefly clarifying that this is a static reference endpoint, but no critical information needed to invoke it correctly 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?

The tool takes zero parameters, so there are no parameter semantics to explain; the baseline for zero-parameter tools is 4. The description's references to fields like screen, transitions, start, and reservedCodeNames describe returned content, not input arguments, and do not create ambiguity.

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

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

The description clearly states that this tool lists HyperCodeMotion capabilities, including formats, layer types, presets, reference conventions, screen rules, runtime layers, transitions, start guide, reserved names, and contract revision. The specific verb 'List' and detailed content make the purpose unambiguous, but it does not explicitly distinguish itself from sibling tools such as get_template or get_motion_recipe.

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 closing instruction 'Call it before designing' gives clear timing and context for using the tool. It does not name alternatives or state when not to use it, but for a prerequisite capabilities-reference endpoint this is adequate 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 read-only, idempotent, closed-world behavior, so the description need not repeat safety facts. It adds the useful claims that results are 'real, validated' and that omitting the name returns the index, but leaves out size, pagination, or output-shape context for a lookup tool.

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

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

The key claim — validated patterns for looks the basics do not give — is front-loaded, and the fallback behavior is stated last without preamble. The long keyword enumeration is dense but serves as discoverability, though it could be more cleanly structured.

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

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

For a single optional parameter with full schema coverage, strong annotations, and no output schema, the description covers what the tool provides and both invocation modes. It is nearly complete, missing only output volume or listing details that an agent might want before calling it blind.

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

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

Schema coverage is 100% and the schema already explains that name is drawn from the index with examples. The description goes beyond the schema by stating what happens when the optional parameter is omitted ('Without name: the index'), which is genuine semantics the schema does not supply.

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 resource — validated JSON/HTML/CSS recipe patterns — and enumerates the distinct looks it covers, which is more specific than the title alone. It does not explicitly differentiate itself from siblings such as get_template or get_capabilities, so an agent must infer that this is the recipe catalog rather than a generic template fetch.

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 one concrete usage rule: without a name you get the index, with a name you get a specific recipe. It never says when to prefer this over get_template or when it is the wrong tool, leaving the main routing decision implicit.

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

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

Adds behavior beyond annotations: the 'comparing' state blocks briefly while the comparison renders, and each terminal state carries specific payload implications (comparison image, template id plus PR link, failure reason). Annotations already cover read-only/idempotent/closed-world, so this extra latency and per-state detail is real added value.

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 dense sentence, front-loaded with the core purpose and then the status enumeration, with no filler. It is slightly run-on across the parenthetical state explanations, but every clause carries 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?

Complete for a simple read-only status check: output schema covers return fields, annotations cover safety, and the description supplies prerequisite, latency caveat, and state semantics. Nothing an agent needs 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 coverage is 100% and the single parameter is documented, so the baseline is 3; the description adds provenance the schema lacks by naming propose_template as the origin of the tracking code, which materially helps an agent supply the right 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 and resource ('Return the status of a gallery template proposal') and ties the input to the sibling tool that produces it (propose_template). The enumerated status values further distinguish it from sibling tools like get_template or get_recreation_brief.

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?

Clearly implies the usage context: call it with the tracking code returned by propose_template, and it explains how to interpret each possible status. It doesn't explicitly say when not to use it or name alternatives for other template queries, but the prerequisite is unambiguous.

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

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

The annotations only declare that it is not read-only, is open-world, is idempotent, and is non-destructive. The description adds substantial behavioral context beyond that: the first call starts frame extraction and may return reference.status: preparing, the caller must supply page metadata because the source sites often refuse this server, upload.script may be required, and an idle unfinished proposal can be discarded after 20 minutes with a restarted brief.

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

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

The description is front-loaded with the purpose and most sentences carry necessary workflow or state information. It is a dense single paragraph that could be made more scannable with structure, but there is little obvious 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?

It covers the complex asynchronous workflow: extraction states, upload branch, the need to repeat calls until reference frames are ready, already-template handling, stale-proposal restart, and invalid-code handling. Since an output schema exists, the description need not explain the full return shape, and nothing critical for correct invocation appears 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 the baseline is 3, but the description adds meaningful context about why the caller supplies title, video, author, and prompt: those values must be read from the page because the source sites often refuse this server. It also emphasizes that adminCode is a moderator code that is required and must never be repeated back, though it does not explain authorUrl.

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

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

The description states a specific action: starting the process of turning a public motion video into an official HyperCodeMotion Studio gallery template. It explains what the tool takes in and returns, and differentiates the step from the later upload and build steps by saying to run upload.script only in the upload state and not to build before seeing the reference frames.

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 an explicit trigger: use it whenever the user sends a prompt-motion.com or oneshotted.io link together with a moderator code, with or without other words. It also describes the repeat-call loop, when to run upload.script, and what happens when the video is already a template or the moderator code is invalid.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds value by confirming no creation/storage side effects and by sketching the shape of the returned design artifact, which goes 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 sentences, front-loaded with the verb and resource before the enumerated return contents. The parenthetical/list detail is dense but each item is informative, so it earns its space; minimal trimming would be possible.

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 an output schema present the description need not detail return fields, yet it still summarizes them, and annotations carry the safety contract. For a two-parameter read tool this leaves nothing an agent needs 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%, and both parameters (template id with example, format enum with default) are fully documented in the schema. The description only restates 'by its id and format' without adding format/default or id-resolution semantics, 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'), resource ('template from the HyperCodeMotion Studio gallery'), and lookup keys ('by its id and format'), then enumerates exactly what is returned (brief, scenes, composition, HTML docs, layers). The closing 'it does not create or store anything' cleanly separates it from the create_hcmotion sibling.

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 when-to-use condition: 'Use it as the design reference when asked to follow a template', plus an explicit negative ('does not create or store anything'). It stops short of naming an alternative sibling (e.g. create_hcmotion) as the thing to reach for when you do want to create, so it is clear context without full 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 only give readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false; the description adds the real behavioral detail: on failure it keeps a draft with code and returns accepted:false with errors, text overflows are warnings only, up to 3 comparisons, and duplicates are not stored twice. That is substantial context beyond the structured fields.

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

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

Front-loaded with the action, then the revision workflow, then the publish caveat, so an agent can stop reading early. Some sentences are long with embedded parentheticals ('estimated text overflows are only warnings', the 1080x1080 dimension list) that slow scanning, but nothing is 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 complex open-world mutation with nested compositions, patch semantics and an output schema, the description covers validation outcome shape, failure recovery, revision limits, dedup and the follow-up tool. Return values are delegated correctly to output_schema and get_proposal_status.

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 goes further by stating the conditional contract: code+patch replaces the three full compositions, card may be omitted on revision, and patch applies to stored compositions. It does not add format detail for url or adminCode beyond the schema.

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

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

States a specific verb and resource ('Submit a recreated video as an official ... gallery template') and names the three artifacts required (source link, three compositions, gallery card). It is immediately distinguishable from publish_template, validate_json and get_proposal_status, all of which are named and given a role.

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

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

Explicitly says 'Do not call validate_json first: this runs the same checks', tells the agent to re-call with the same code for revisions (up to 3 comparisons), to prefer patch over full compositions unless redesigning, and that nothing is published until publish_template. When-to-use and when-not-to-use are both covered.

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 that gallery videos are rendered, code is committed to a branch, and a pull request is opened for moderator approval or discard — significant, non-obvious side effects and a human review gate. Given a three-parameter mutation with openWorldHint=true, a note on timing or whether the call blocks until rendering finishes would have completed it.

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 dense paragraph that front-loads the action, then the required inputs, then the downstream effects. Almost every clause carries a distinct fact, though the run-on syntax where rendering, branching, and PR approval are strung together costs a little readability.

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?

An output schema exists and annotations cover the safety profile, so the description only needs to explain the human-facing lifecycle — which it does: inputs, rendering, branch/PR, moderator merge-or-discard, and where to check status. Nothing an agent needs before calling 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 coverage is 100%, so all three parameters are already documented with meaning and constraints (600-char notes, moderator-only adminCode, never repeat it). The description restates the parameter roles in prose but adds no syntax or format detail beyond the schema, so the baseline 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?

Specific verb and resource: 'Publish a compared template as an official ... gallery template', which sets it apart from ordinary template creation. It does not explicitly frame the boundary with the sibling propose_template (presumably the earlier comparison step), so differentiation is implied by the word 'compared' rather than stated.

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

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

Gives a clear precondition for use ('once its comparison with the original looks faithful') and routes to get_proposal_status for the pull request link. It stops short of stating when NOT to use it or naming propose_template as the alternative for an un-compared template.

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?

Beyond the annotations, the description discloses file size limits (150 MB per file, 200 MB per project), the 24-hour upload lifetime, the network requirement for the curl script, the fallback browser workflow, and the exact shape of returned values. The annotations are consistent with an upload-initialization operation that is not read-only, destructive, idempotent, or open-world in the sense of arbitrary external fetching.

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

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

The description is dense and largely front-loaded, with no filler sentences. It is slightly lengthy for a single paragraph, and breaking the return values and fallback workflow into clearer segments would improve scanability.

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

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

Given the tool's complexity, the description covers what the tool does, how to invoke it, what it returns, size limits, network requirements, fallback behavior, and upload duration. An output schema exists, but the description still gives enough context for an agent to use the tool 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?

The schema already has 100% description coverage for the files parameter and its id/name fields. The description nevertheless adds useful meaning by explaining that ids are what layers will use as props.asset and by providing file-size constraints not present in the schema.

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

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

The description states a specific verb and resource: opening an upload for the user's own images, videos, audio, or fonts that are not at a public https link. It explains the downstream purpose, packing files inside the .hcmotion via create_hcmotion, which clearly distinguishes it from sibling tools.

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

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

It explicitly says when to use this tool: files not at a public https link, such as attachments or sandbox files. It also gives a clear operational sequence, trying the script first and falling back to the page if the shell cannot reach the host, and notes the downstream create_hcmotion usage.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower; the description adds real behavioral context — the specific rejection rules (text overflow, crossing canvas, line-height below 1) and the RESERVED_NAME_DECLARED warning. It also discloses the important limitation that passing validation does not guarantee a successful render.

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

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

Front-loads the core action and payload types, then enumerates rules compactly in three sentences with zero filler. Slightly dense with rule specifics but every clause carries 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?

An output schema exists, so return values need not be explained, and the description supplies the validation rules and a key limitation. Nearly complete for an agent to call it correctly; only workflow placement (when in the pipeline to call it) is left implicit.

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

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

Schema description coverage is 100%, so the schema already documents both 'json' and 'composition'. The description adds no format or syntax detail beyond restating that patches/designs are accepted, so baseline 3 applies.

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

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

Uses a specific verb ('Check/validate') over three named payload types (composition, design, improvement patch) with parenthetical contents, making it clearly distinct from siblings like create_hcmotion. An agent can tell exactly what this operation does 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?

Implies usage (validate a payload before rendering) and adds the useful caveat 'This is not proof of a successful render', but never states when to choose this over alternatives or any prerequisites/workflow ordering. 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.