Motion by Frapea

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

Goes well beyond the annotations, which only say readOnly=false, destructive=false, idempotent=false. It discloses the real side effect (the run takes over the stage and the composition under test becomes the one on screen), explains why readOnly is false, notes buffering is tolerated, that any error ends the run, the ~20 s response window, and the incomplete reasons (tab hidden, interrupted, edited). It also reassures that source and props are unchanged.

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?

Purpose is front-loaded in the first sentence and the response shapes are enumerated compactly. The stage-takeover sentence partially restates the opening line, and the response-shape clauses are dense, but no sentence is wasted.

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

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

There is no output schema, yet the description enumerates every response shape an agent must branch on (running/done/incomplete) with their fields. Combined with the side-effect disclosure and polling contract, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds genuine meaning for 'id' by defining the continue-polling contract ('call again with the same id to keep waiting on the same run'), which the schema's terse 'Omit for the active one.' does not convey.

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 ('Plays a composition on the user's stage from the first frame to the last') and gives the outcome it reports ('whether it got to the end'). It also explicitly distinguishes itself from the sibling inspect_composition by noting it uses the same preview a person watches, which inspect_composition does not.

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

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

Names the closest alternative (inspect_composition) and the axis on which they differ, and spells out the polling protocol: a {status:"running"} response means call again with the same id. What's missing is an explicit recommendation of when to prefer one over the other (e.g., static analysis vs. real rendering), so the choice is still partly inferential.

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=true, so the bar is lower, and the description still adds real value: the source is discarded, the tab disappears, and there is no implicit fallback to the active composition. It does not cover error behavior if the id is stale, which keeps it from a 5.

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

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

Three short sentences, front-loaded with the action and its consequence, followed by the intended scenario and the failure-mode caveat. No repetition of the title and no filler.

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

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

For a two-parameter mutation with no output schema and annotations already declaring the destructive/idempotent profile, the description covers what an agent needs to call it correctly. The only minor gap is what happens when the id is invalid or already closed.

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

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

With 100% schema coverage the baseline is 3, but the description adds meaning beyond the schema: the id must be explicit and is never inferred from the active composition, clarifying a semantic the schema's 'Required.' note does not convey. The token parameter's role is left entirely to the schema.

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

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

States a specific verb and resource ('Closes a composition') plus the concrete side effect ('removes it from the user's tabs; its source is not kept'), which cleanly separates it from sibling list/inspect/update tools. An agent can distinguish it from delete_media or update_composition 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?

'Meant for drafts made along the way' conveys the intended context of use, and 'never falls back to the active composition' warns of a failure mode an agent might otherwise assume. It stops short of naming alternatives or stating when not to close, so it is clear context rather than full routing 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 only give the flags (readOnlyHint=false, idempotentHint=false, destructiveHint=false); the description goes further by explaining WHY non-idempotency matters — 'The code works once; the token is what stays valid.' That is exactly the retry behavior an agent needs to know. It leaves failure modes (expired or already-used code) unstated.

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

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

Three short sentences, front-loaded with the action and the required input, then the return value, then the lifecycle constraint. No sentence is redundant and nothing is buried.

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

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

With no output schema, the description carries the burden of explaining the return value and does so ('a session token that every other tool takes'). For a single-parameter tool this is nearly sufficient, though it omits what an agent should expect if the code is invalid or the token later expires.

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 a concrete format example ('K7M4-P2Q9') and provenance ('under the Connect MCP button') that the schema's 'eight-character pairing code shown on the Motion page' does not convey as precisely.

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+resource ('pairs this agent with a Motion browser tab') and immediately scopes it with the exact input ('eight-character code the user sees under the Connect MCP button'). It is clearly distinct from every sibling, which all operate on compositions/media/playback rather than establishing the session.

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?

'Returns a session token that every other tool takes' tells the agent this is the prerequisite step before any sibling tool, which is strong ordering guidance. It does not address the sibling create_session or explain what to do when pairing is not needed, so it stops short of explicit when-not/alternatives.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false; the description adds the meaningful behavioral detail that a tab is opened in the user's page, which is a visible side effect not captured by the annotations. It omits that repeated calls create duplicate compositions/tabs (relevant to idempotentHint=false) and says nothing about the token/session prerequisite.

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

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

Four tight sentences that front-load what happens and then layer the essential `files` constraint and doc pointers. The final partsBoard sentence is the weakest link since it describes a prop absent from the schema.

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

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

For a 9-parameter mutation tool with no output schema, the description never says what the call returns (e.g., a composition identifier the agent needs for later set_props/update_composition calls), and the undocumented boilerplate params (width/height/fps/durationInFrames) are left to name inference. The read_skill pointers partly offset this, but key lifecycle information 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?

With only 33% schema coverage across 9 parameters, the description does useful work by explaining `files` (path-to-source map that must include the entry) and restating the entry default. But fps, width, height, durationInFrames, and name get no semantic elaboration, and the 'partsBoard prop' it mentions does not exist anywhere in the schema, which actively muddies the parameter picture.

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 ('Creates') plus resource ('a new composition from TSX source') plus the non-obvious side effect that it opens the result as a tab in the user's Motion page. That side effect alone distinguishes it from update_composition, get_composition, and close_composition in the sibling list.

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

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

Explicitly routes the agent to read_skill with two topic names (motion for API specifics, motion-craft for design), which is actionable guidance before calling. It does not, however, state when to prefer update_composition over creating a new one or what prerequisites (e.g., an active session from connect) are required.

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

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

Annotations only declare the mutation profile; the description adds real behavioral context on top: the return is a browser-opening link, the session supports immediate composition edits, frame rendering/playback/media require the tab to be open, and the scene expires 24 hours after the last change. The state lifetime and capability boundary are exactly what an agent cannot infer from 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?

Four sentences, front-loaded with the selection condition, and each carries distinct information (trigger, return value, limitation, retention). The clause 'Compositions can be created and edited at once' is the only slightly loose phrasing, but 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?

With zero parameters and no output schema, the description carries the full burden and meets it: it explains the trigger, what is returned, what the session can and cannot do without the tab, and how long state persists. Nothing an agent needs to call this 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 semantics to explain and the baseline of 4 applies. The description spends its words on behavior rather than restating an empty schema, which is the right allocation.

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 ('Starts a Motion session') plus the exact condition that scopes it ('when the user has no pairing code'), which implicitly separates it from connect. It also names the returned artifact (a link) and references wait_for_tab, so an agent can identify the tool 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 a clear trigger condition ('no pairing code') and an explicit exclusion with a pointer to the alternative for media work ('see wait_for_tab'). It never names the sibling that handles the with-pairing-code case, so the selection rule is strong but not fully closed.

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 past the destructiveHint/idempotentHint annotations by explaining what actually happens: a copied file is removed from the browser, a linked file remains on disk and only leaves the library. It also discloses the downstream consequence that compositions using the deleted file report missing footage — exactly the kind of consequence an agent needs before invoking a destructive 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?

Three short sentences, front-loaded with the action and scope, then the copied-vs-linked distinction, then the downstream effect. Every sentence carries distinct information with no repetition of the 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 two-parameter destructive tool with full schema coverage and no output schema, the description covers the action, the two file-source behaviors, and the impact on compositions. Minor gaps remain around what happens for unknown ids, but nothing essential to correct 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. The description reinforces that deletion targets ids (plural, suggesting batch semantics) but adds no format or constraint detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Deletes files from the user's media library by id'), which cleanly separates it from siblings like get_media, list_media, put_media, and organize_media. The scope (per-file deletion by id) is unambiguous.

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

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

Usage is implied by the destructive nature and 'by id' phrasing, but the description never says when to choose this over organize_media or other library-management tools, nor any prerequisite beyond the token. Adequate, but the agent must infer the boundary.

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

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

Annotations already cover read-only, idempotent, non-destructive, closed-world behavior. The description adds useful behavioral context by specifying what the read returns and how it relates to update_composition, though it omits error or size/performance notes.

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

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

The description is a single front-loaded sentence with no wasted words. The core purpose and returned contents are stated 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?

There is no output schema, so the description must explain return contents; it does so by naming manifest, source files, and prop values. Parameter details are covered by the schema, leaving no important gap for this read-only retrieval 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 the id and token parameters are already documented in the schema. The description does not add parameter-specific meaning beyond what the schema provides.

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

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

The description uses a specific verb and resource: 'Returns one composition in full.' It enumerates the returned contents (manifest, every source file, current prop values), which clearly distinguishes it from list/inspect siblings.

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 establishes clear usage context by saying this is 'the state an update_composition edit applies to.' However, it does not explicitly name alternatives such as inspect_composition or state when not to use it.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so safety is covered; the description adds genuinely new behavior: base64 encoding and a ~600 KB cap, plus a routing hint to a cheaper alternative. It stops short of saying what happens at the cap (truncated vs. error), which is the one thing an agent most needs to know.

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; the size cap is front-loaded and the alternative is offered immediately after. 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 simple two-parameter read tool with full annotations and no output schema, the description covers return content (base64 bytes) and limits. The residual gap is the ambiguous cap semantics and the undocumented id parameter.

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%: token is documented, id is bare. The description never mentions either parameter, so it adds no meaning about what id refers to (file id? message id?) or how the session token is scoped, leaving half the parameters undocumented everywhere.

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

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

Specific verb+resource: "Returns the raw bytes of one file, base64, capped at about 600 KB." It also implicitly separates itself from text-oriented readers by stating it returns raw bytes. An agent can distinguish it from inspect_media and list_media without opening schemas.

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

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

Explicitly names the alternative (inspect_media) and the exact conditions that select it: "For larger files and for video." That is a when-to-use/when-not-to-use pair with a concrete tradeoff (size).

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial non-obvious behavior on top: operation while the tab is hidden or closed, the current-vs-earlier distinction for problems an edit has left behind, and the fact that other tool results may carry their own `problems` list. It also flags the reporting boundary of an empty result.

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 framing is front-loaded in the first clause, and the long failure enumeration earns its space by showing scope. The final sentences about `current`/`earlier` and cross-tool `problems` lists are terser than the rest and read as compressed notes, slightly reducing readability without being wasteful.

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

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

With no output schema, the description carries the burden of explaining return shape and does so at a high level — a problems list with `current` and `earlier` buckets, plus warnings. The precise structure of those buckets is left oblique, but for a diagnostic read tool the essentials an agent needs to act are present.

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 `id`, `token`, and `includeWarnings` are already fully documented, and the description adds nothing parameter-specific beyond what is in the schema. Baseline 3 applies; the `current`/`earlier` discussion concerns result fields rather than inputs.

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 ('Lists what went wrong in the user's tab') and immediately enumerates the concrete failure classes it covers — render failures with engine messages, stalled previews, load/decode failures, missing footage, failed exports, killed pages, warnings. It is clearly distinguishable from check_playback and from the inspection tools, so an agent can pick it 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 real operating context ('works while the tab is hidden or closed') and names the alternative with its condition: an empty list only covers what the tab has played, while check_playback does a full pass. It does not spell out the flip side — when this tool should be preferred over check_playback for a first look — leaving that one inference to the agent.

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 readOnly/idempotent annotations, the description adds that nothing is saved or changed, that rendering happens in the user's tab, that output is a single labelled contact sheet, and that props apply only to this render. It also explains the meaning of per-frame content share, which helps the agent interpret anomalous frames.

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 core action and then moves efficiently through frame selection, resolution, prop merging, and result interpretation. Each sentence contributes operational detail without repetition.

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

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

With annotations covering safety and idempotency, and no output schema, the description provides enough about the returned contact sheet, labelling, resolution, and content-share signal for an agent to invoke and interpret 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?

Schema coverage is high at 75%, and the description adds useful semantics beyond the schema for the two most nuanced parameters: atFrames has a 12-frame cap and a meaningful default spread with scene-boundary labels, while props are merged over composition props for this render only. The token and id parameters are left to the schema, which is acceptable given their coverage.

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

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

The description opens with a specific verb and resource: it renders frames of a composition in the user's tab and returns a labelled contact sheet. It explicitly scopes the operation as non-persistent, which distinguishes it from mutation-oriented siblings like update_composition or create_composition.

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

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

It gives clear invocation context by explaining that omitted atFrames produces an even spread plus scene joins, and that higher-resolution single frames are for checking detail. However, it does not explicitly name alternatives such as check_playback or get_composition, so the agent must infer when this visual inspection tool is preferable.

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, and non-destructive behavior, so the safety profile is covered. The description adds genuinely new behavioral facts: the output is a single image contact sheet rather than a list, and atSec is capped at 12 timestamps with even-spread defaulting. It stops short of saying what happens for a static image (are timestamps ignored?) or whether failures are surfaced per-moment.

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 with zero filler: the first front-loads what the tool does and returns, the second covers the one parameter behavior an agent cannot infer. Nothing is repeated from the annotations or 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?

With annotations carrying the safety profile and no output schema, the description carries the return-shape burden itself and does so explicitly (one image, labelled cells). For a three-parameter read tool, an agent has enough to invoke it correctly aside from minor edge cases like image (non-video) inputs.

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% and the description covers the only undocumented non-trivial parameter semantics that matter: atSec caps at 12 and, when omitted, moments are spread evenly over the clip — a default behavior absent from the schema. The 'id' parameter still gets no explanation (media id vs composition id?), which keeps this below top marks.

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 ('looks inside an image or video') and, crucially, what it produces: one contact sheet with each requested moment as a labelled cell. This distinguishes it functionally from sibling retrieval tools like get_media and list_media, which the agent can tell apart without opening either schema.

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

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

Explains the atSec argument's intended use (spread moments evenly when omitted), which implies when the tool is useful. However, it never explicitly says when to choose this over get_media versus when not to, or what preconditions (e.g. valid media id from list_media) are needed, so routing guidance is only implied.

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

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

The annotations already declare the operation as read-only, idempotent, non-destructive, and not open-world, so the safety profile is fully covered. The description adds useful behavioral context by saying it reports the on-screen composition, but it does not describe ordering, empty results, or any session-level constraints 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 a single front-loaded sentence with no wasted words. It states what is listed and the key output distinction of which composition is on screen.

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 list tool with full schema coverage and annotations, the definition is almost complete. It explains the core return content, including the active composition, though it could optionally clarify result ordering or behavior when no compositions are open.

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 single token parameter is already fully documented as coming from connect. The description implies session scoping by saying 'open in the session' but does not add any parameter-level meaning beyond the schema.

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

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

The description gives a specific verb and resource: it lists the compositions open in a session and identifies the one on screen. That scope is clear enough to separate it from single-composition tools, but it does not explicitly name or contrast against sibling tools like get_composition or inspect_composition.

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 usage is implied: an agent can infer this is for discovering open compositions before inspecting or updating one. However, there is no explicit statement of when to use this versus get_composition or inspect_composition, and no prerequisites or exclusions are given.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely new behavioral context: the 'linked' vs 'copied' storage distinction and the fact that a linked file may require the user to re-grant access after a reload. That is a real caveat an agent would otherwise miss.

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 return shape, then the non-obvious storage caveat. No filler or restatement of the title.

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

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

There is no output schema, so the description usefully names the returned fields and the one field with surprising semantics. It is nearly complete for a read-only list tool; only the lack of routing guidance against sibling media tools keeps it from full marks.

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 are documented in the schema, including 'Omit for all' for path, so the baseline of 3 applies. The description's detail about the `storage` field concerns return values, not parameter meaning, so it adds nothing to 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 and resource ("Lists the user's media library") and enumerates the returned entity types (folders, files with id/name/kind/size/folder). It is separable from siblings like get_media or inspect_media, though it never explicitly contrasts itself 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?

Usage is only implied: the description shows what a listing yields, which suggests when to reach for it, but it never states when to prefer this over get_media, inspect_media, or organize_media, nor any prerequisite such as needing a connected session token.

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 idempotentHint=false, so the description is not carrying the full burden. It nonetheless adds a genuinely non-obvious behavior: deleting a folder reparents its contents up one level and deletes nothing, which reconciles the destructiveHint=false claim. It does not mention whether 'move' overwrites or errors on name collisions, or that repeated moves are not idempotent.

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 overall verb, then organized action-by-action in a single dense sentence. No filler and no repetition of the title. The telegraphic parenthetical style is efficient, though slightly compressed for a 7-parameter tool.

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

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

For a mutation tool with no output schema and 7 parameters, the description covers action semantics well but says nothing about results: an agent calling 'createFolder' cannot tell whether it receives a folder identifier to use in a subsequent move. Collision behavior on move is also unstated, leaving a meaningful gap for multi-step workflows.

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 14%, so the description must compensate, and it largely does: it maps ids, toFolder, name, parent (marked optional) and folder to their respective actions. The token is documented in the schema itself. It leaves the format of ids, the meaning of an absent parent (root?), and path syntax for folder/toFolder to inference.

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 ("Moves files and manages folders") and enumerates the three action modes, so the tool's scope is unambiguous. It also explicitly carves out file deletion and attributes it to the sibling delete_media, which differentiates it from that 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?

Each action is paired with the parameters it needs ('move' with ids+toFolder, 'createFolder' with name+parent, 'deleteFolder' with folder), so selection is mechanical. It also names the clear exclusion: deleting files is delete_media, not this tool. It stops short of stating prerequisites such as the session token or whether target folders must already exist.

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

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

Annotations already declare non-destructive, open-world, non-idempotent behavior, and the description goes well beyond them: browser-fetch semantics, CORS requirements, the ~700 KB and 10 MB ceilings, and the exact upload endpoint with token/name query params. These are real operational constraints an agent cannot infer from the schema.

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

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

Three dense sentences with the non-destructive guarantee front-loaded, then each input mode with its constraint. No sentence is filler; the size limits and CORS caveat are exactly what prevents failed calls.

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 never says what a successful add returns (e.g., the new media id), which an agent would want. Everything else an agent needs to choose an input path and call correctly is present.

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 genuine meaning: `url` requires public https and CORS, and `data` carries a ~700 KB size cap. `folder`, `name`, and `token` are left to the schema, which is acceptable given full coverage.

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

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

States a specific verb and resource: 'Adds a file to the library as a new item; nothing existing is replaced.' This clearly separates it from delete_media and organize_media. It doesn't explicitly name a sibling alternative, but the non-replacement clause distinguishes it from any update path.

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 explicit routing rules: use `url` for public https hosts with CORS headers, `data` for small base64 assets under ~700 KB, and the raw POST to /media/upload for larger files up to 10 MB. Each branch is conditioned on a concrete, checkable property of the caller's situation.

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 and destructiveHint=false, so the description is not burdened with the safety profile; it instead adds the important behavioral fact that the result is plain text and that skipping the 'motion' guide causes downstream composition failures. It does not indicate guide length or whether reads are cheap enough to repeat liberally, which would have completed the picture.

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 core action is front-loaded in the first sentence, and the semicolon-delimited topic list carries dense, non-redundant information in a single paragraph. Given the 0% schema coverage of the enum, every clause about the topics earns its place; nothing is repeated from 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?

With one required enum parameter, no output schema and rich annotations, the description covers everything needed: what is returned (text), what each topic contains, and the cost of omitting the contract guide. No further detail is required to invoke this 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?

Schema description coverage is 0%, so the schema gives only a bare enum, yet the description compensates by defining the meaning and intended use of every one of the eight allowed values. An agent can choose the correct topic without any external knowledge.

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 ("Returns one of Motion's authoring guides as text") and then enumerates all eight guide topics, so the agent knows exactly what comes back. Highly distinguishable from siblings like get_composition or inspect_composition, which operate on compositions rather than documentation.

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?

Each enum value is annotated with when to reach for it — 'motion' is framed as mandatory ('compositions written without it usually fail'), 'motion-craft' as the fix for output that 'look[s] generated', and the remaining topics are scoped to typography, named looks, sequencing, worked examples, live workflow and critique. This functions as explicit topic-selection guidance, and no exclusion clauses are needed because no sibling tool competes for this job.

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=true; the description goes beyond them by disclosing the merge semantics ('merged by key; keys sent replace their current values'), which explains exactly which state is overwritten and why repeated calls are safe. It does not confirm or deny the destructive hit on keys omitted from the call, but the core mutation behavior is covered.

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

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

Two short sentences with no waste, and the core behavior plus merge semantics are 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 destructive nested-object mutation with no output schema, the definition covers the write semantics but leaves out two things an agent needs: how to discover valid prop keys (e.g., via inspect_composition) and how it differs from update_composition. Adequate but with a 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 coverage is only 33% — only 'token' is documented. The 'props' object is an untyped nested object with no key list or value format, and the description only says values are merged by key; it never says what prop keys exist or what the 'id' parameter identifies. The merge rule is helpful but does not compensate for the untyped props payload.

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 ('Sets prop values on a composition') and adds a useful conceptual anchor: these are the same values the user's controls change. It does not, however, distinguish itself from the sibling 'update_composition', so an agent must still guess which mutation to use.

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

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

Usage is only implied by 'the same values the user's controls change', which hints at the intent but gives no explicit when-to-use rule, no prerequisites, and no comparison against update_composition or inspect_composition. The agent is left to infer.

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 idempotentHint=true. The description adds useful behavioral context beyond those annotations: 'Changes nothing else', that 'done' marks the job finished, that 'problem' marks a blocker, and that step/of draw a progress bar. 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?

The description is short, front-loaded with the core purpose, and each sentence earns its place: purpose, kind/progress behavior, non-interference, and workflow pointer. There is no wasted text.

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

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

Given that annotations already cover the safety profile and the input schema is fully documented, the description is complete enough for an agent to call this tool correctly. It explains the tool's role, key status semantics, and where to find workflow guidance.

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 all five parameters. The description reinforces the meaning of kind and progress-bar parameters, but does not add substantial semantics beyond what the schema already provides. With full schema coverage, 3 is the appropriate baseline.

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

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

The description states a specific verb and resource: it shows one short status sentence in the user's Motion tab while work is in progress. This is clear enough to distinguish it from sibling tools like wait_for_tab or check_playback, though it does not explicitly name an alternative.

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

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

It gives clear context for when to use the tool: while work is in progress, so the user can tell progress from a stall. It also explains kind 'done' and 'problem', and points to read_skill {topic:'motion-workflow'} for workflow fit. It stops short of explicit 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 destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description still earns credit by disclosing the actual mutation model — per-path file replacement, omitted files retained, and prop values preserved when the schema changes. That directly answers what gets destroyed versus kept, which the annotations alone could not.

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

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

Three short sentences, front-loaded with the action, and every clause carries distinct information about partial-update behavior. No filler or restatement of the name.

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

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

For a 9-parameter destructive mutation with no output schema, the description covers the parts an agent is most likely to get wrong (file replacement and schema migration). It could still note that unspecified scalar fields are untouched or what the call returns, but with annotations carrying destructiveness and idempotency it is close to 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 only 22%, so the description must carry the load; it does explain the two non-obvious parameters — `files` as a path-to-content map and `schema` as a partial migration — which is high-value. The six remaining scalars (fps, name, width, height, durationInFrames, plus the required token) get no mention, leaving a real compensation 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 and resource ("Edits an existing composition") and immediately clarifies the semantics of the edit (per-file replacement, schema-preserving). It is clearly distinguishable from create_composition, though it does not name any sibling explicitly.

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

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

Usage is implied rather than stated: "edits an existing composition" tells an agent this is for modifying, not creating, and "files not sent are kept" signals partial-update semantics. But nothing directs the agent away from set_props for prop changes or toward create_composition for new compositions, and no prerequisites (token, active vs. explicit id) are given.

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

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

Beyond the readOnly/idempotent annotations, it discloses both terminal outcomes and timing: returns immediately on connect, or after roughly 25 seconds with tabConnected false. This is exactly the kind of waiting/timeout behavior an agent cannot infer from annotations.

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

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

Three short sentences, front-loaded with the wait condition, then the timeout semantics, then the downstream dependency. Every sentence carries distinct 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 still conveys the return signal (tabConnected false on timeout) and the ~25s duration, plus why the caller cares. Nothing essential for correct 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?

The tool takes zero parameters, so there is nothing to disambiguate; the baseline applies. The description correctly implies it is parameterless by describing a pure wait condition.

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 event ('Waits until the user's Motion tab connects to the session') and names the sibling that produces the link (create_session), so it is distinguishable from connect and the tab-management family at a glance.

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 concrete trigger ('for example after they open the link from create_session') and a prerequisite for other tools ('Tools that render or touch media need the tab'). No explicit when-not/alternative routing, which keeps it just below a 5.

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