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

With annotations limited to hints, the description carries the burden and delivers: it reveals the two-phase behavior (slot creation only, no byte upload), the auth-omission requirement for the PUT, the ordering dependency on generate_motion_from_video, the 30-second/250 MB constraints, and a security caution to keep signed URLs private. None of this contradicts 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?

Five short sentences with the primary purpose front-loaded, followed by scope clarification, workflow, and grouped constraints. No filler; every sentence 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 two-phase tool with no output schema, the description names the key returned field (mediaUploadURL) and lays out the full lifecycle. It does not mention slot expiry, behavior on repeated calls, or error cases, but an agent has what it needs to invoke and follow through 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 prose must compensate. It adds the 250 MB limit that the schema cannot express and frames the media array as 'selected local videos,' clarifying the intent behind name/extension. It does not explicitly explain every field (e.g., resolution format), but the schema's enum, pattern, and maximum make those partially self-documenting.

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 opening sentence 'Prepare signed upload URLs for video references' gives a specific verb and resource, and the second sentence disambiguates from actual byte upload ('it does not upload the file bytes'). It also distinguishes the tool from the sibling generate_motion_from_video by positioning this step before it.

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

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

The description gives explicit workflow instructions: use the client's authorized file tools to PUT each video to the returned mediaUploadURL without an API key header, and upload before calling generate_motion_from_video. It provides clear context but does not name a competing alternative tool or state when not to use this one.

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 that the call consumes generation credits, returns a batch ID for tracking, and should not be repeated merely to check progress. This is important side-effect and lifecycle information that the annotations alone do not provide. No contradiction with the annotations exists.

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

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

The description is three short, purposeful sentences: it states the action, the return value, and the critical usage caveat about credits and polling. Every sentence adds value and there is no redundancy or 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 an asynchronous creation tool with no output schema, the description provides the essential return contract (a batch ID), the cost implication (credits), and the follow-up polling tools. Together with the fully documented input schema, an agent has enough context to invoke the tool correctly and avoid common misuse.

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

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

Schema description coverage is 100%, and every parameter including nested objects has detailed descriptions, examples, enums, and defaults. The description itself adds no parameter-specific semantics, but the schema fully carries that burden, so the baseline score of 3 is appropriate.

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

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

The description clearly states the action and resource: 'Generates motion animation based on text prompts.' It also distinguishes itself from the sibling generate_motion_from_video by specifying the text-prompt input modality, and clarifies it is a creation/submission tool rather than a retrieval or listing tool.

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

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

The description gives explicit workflow guidance: submit once, then use get_batch and list_batch_motions to poll, and do not resubmit to check progress. It does not explicitly name generate_motion_from_video as the video alternative, but the text-prompt qualifier and sibling names make the choice reasonably clear.

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

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

Annotations are sparse (safety hints only), so the description carries the disclosure burden and earns it: credit consumption, the submit-once-then-poll async pattern, the 1–4 person capacity, and the requirement to preserve actor exports and MHR assets across calls are all non-obvious behaviors that a caller would otherwise discover by trial and error. No contradiction with the annotations; 'submit once' aligns with idempotentHint=false.

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, followed by prerequisites, cost/workflow, and downstream usage — every sentence earns its place and no filler exists. The final sentence packs three ideas (preservation, retargeting routing, moveInPlace) into one dense block, so it is efficient but slightly bundle-heavy.

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 tool (7 top-level params, nested exportSettings with 13 sub-properties, no output schema, minimal annotations), the description supplies what matters most: purpose, prerequisites, async polling workflow, capacity limits, and sibling routing. Its main gaps are not describing what the submit response returns (e.g., the batch ID needed to poll get_batch) and never linking mediaIDs to the create_media_upload sibling.

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 14%, so the description must compensate and partially does: it grounds mediaIDs (uploaded IDs), numPeople (1–4), facialCapture (optional), and gives moveInPlace a purpose ('preserve interactions and shared world placement'). However, loop and batchName receive no semantic grounding, and the exportSettings object is only described as needing to be 'complete' without touching its many sub-fields.

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?

Opens with a specific verb and resource: 'Capture editable body, hand and optional face performance from uploaded videos using Comic 4.' It names the input (uploaded videos), the pipeline (Comic 4), the output (editable performance), and the capacity constraint (1–4 people). The 'from uploaded videos' qualifier clearly separates it from the sibling generate_motion, which handles the non-video 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?

Gives explicit prerequisites ('Requires uploaded media IDs and complete export settings'), a concrete workflow ('submit once, then poll get_batch and list_batch_motions'), and routes the agent to get_motion with the exact keys (characterID and bodyIndex) for per-actor retargeting. It also warns to keep moveInPlace false to preserve interactions and shared world placement — actionable guidance an agent can execute without further inference.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety and idempotency. The description adds that the response includes status, progress, and export settings, which is useful but not a rich behavioral disclosure beyond annotations.

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

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

Two sentences with the main action and relevant context front-loaded. Every sentence earns its place; there is no repetitive or extraneous wording.

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

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

For a single-parameter read-only tool with no output schema, the description gives enough context: what it returns, how to use it, and where the batch ID comes from. It could additionally point to list_batch_motions for obtaining batch IDs, but the description is functionally sufficient.

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 parameter already has a clear description and example. The description adds minimal parameter meaning, mostly linking batchID to the creation endpoints, but does not provide additional format or lifecycle details.

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 ('Retrieves') and clearly identifies the resource as batch details, listing status, progress, and export settings. It does not explicitly contrast with sibling tools like get_motion or list_batch_motions, but the batch-specific scope is clear enough.

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

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

The second sentence gives a direct use case: check the status of batch jobs created via /motion/fromVideo or /motion/fromText. It does not state when not to use it or name an alternative tool, but the intended context is clear.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false; the description adds valuable lifecycle behavior beyond that: polling semantics, state values (COMPLETE/FAILED), the presence of estimatedSecondsWaitTime during processing, and the exact URL fields returned. This is exactly the kind of context annotations cannot convey.

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 compact yet information-dense, front-loading the main purpose before detailing the polling lifecycle and resulting URLs. Every clause earns its place and the structure follows the natural call flow.

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

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

There is no output schema, but the description enumerates the key response fields and gives enough polling context for an agent to use the tool correctly. It could additionally describe failure payloads or other possible uploadStatus values, but those are minor gaps for a single-parameter, read-only 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 coverage is 100%: the single characterID parameter has its own description and example. The description does not add new parameter syntax or format details beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Retrieves') and names the exact resource ('a character's details') plus the distinctive payload (uploadStatus and presigned download URLs). This makes it immediately distinguishable from sibling list tools like list_characters and other get_* tools by resource and purpose.

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 when-to-use instruction: 'Poll this after submitting an upload until uploadStatus is COMPLETE (or FAILED)'. It does not spell out when-not-to-use or name alternative tools, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds valuable context beyond that: the URL is a 'current signed download URL' and 'media registration alone does not prove that file bytes have been uploaded,' which prevents the agent from assuming upload completion. No contradiction with annotations.

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

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

The description is two sentences with no filler. The main purpose and output are front-loaded in the first sentence, and the important caveat about upload status is placed second. Every sentence contributes necessary information.

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

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

For a simple one-parameter read-only tool, the description is complete: it states the returned data (media item and current signed download URL), explains how to obtain the ID, and warns about the upload caveat. Since there is no output schema, the description adequately covers return semantics.

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 only provides mediaID as a required string with minLength 1 and no description. The tool description adds meaningful semantic guidance by indicating that mediaID should come from a motion's sourceVideoMediaID. It does not elaborate further on ID format, but for a single required parameter this is a useful addition.

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: 'Retrieve an accessible reference media item and its current signed download URL.' It clearly specifies both the action and the returned data, and distinguishes itself from motion/scene/character siblings by pointing to sourceVideoMediaID from a motion and the original reference relationship.

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 gives clear when-to-use context: use a sourceVideoMediaID from a motion to retrieve the original reference. It does not explicitly name alternative tools or state when not to use this tool, but the guidance is sufficient for a tool with no close sibling overlap.

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 read-only, idempotent, non-destructive profile, so the description only needs to add context beyond that. It adds the retargeting behavior and the primary-vs-batch distinction, but it does not explain what shape 'status/downloads' take or whether 'apply' changes anything persistently. No contradiction with annotations is present.

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 compact at three sentences and front-loads the main retrieval purpose before the retargeting variant and the sibling pointer. The first sentence is slightly overloaded by joining retrieval and retargeting with 'or,' but there is no redundant 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?

With no output schema, the description should clarify return semantics; 'primary motion status/downloads' gives only a partial picture. The sibling reference to list_batch_motions and the parameter schema fill in some gaps, but an agent is left unsure exactly what fields or file payload to expect from get_motion.

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

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

Schema description coverage is 100%, so the baseline is 3; the schema already documents motionID, fps, bodyIndex, characterID, and downloadType with examples and enums. The description adds useful context about multi-person Comic retargeting and zero-based indexing but mostly restates schema information.

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 'Retrieve primary motion status/downloads', identifying a specific verb and resource, and also mentions the retargeting capability via characterID/bodyIndex. It distinguishes itself from list_batch_motions by pointing out that the sibling returns 'complete ordered...output arrays,' but the qualifier 'primary' is vague enough to keep it from full clarity.

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 condition: for multi-person Comic retargeting, provide characterID and zero-based bodyIndex. It also tells the agent to use list_batch_motions when complete output arrays are needed, which is a clear when-not/alternative. However, it does not contrast with other motion-related siblings such as search_motions, list_motions, or get_batch.

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

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

Annotations already declare this tool as read-only, idempotent, non-destructive, and open-world, so the description carries a lighter burden. It adds the useful context that access is limited to scenes the service account can access, but it does not describe behavior for missing or inaccessible scenes.

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, well-structured sentence that communicates the core action and access scope with no filler. It is appropriately sized for a tool with one parameter and a straightforward purpose.

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 retrieval tool with a fully documented single parameter and strong annotations, the description is largely sufficient. It does not specify the return payload or error behavior, but the absence of an output schema and the simplicity of the operation make this a minor gap rather than a critical one.

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 documents the single sceneID parameter with type, example, and description, giving 100% coverage. The tool description adds no additional meaning about the parameter beyond what the schema provides, so the baseline score is appropriate.

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

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

The description states a specific verb ('Retrieves') and a clear resource ('a scene'), making the tool's function immediately understandable. It also adds the scoping qualifier 'accessible to the authenticated service account,' which helps distinguish it from broader scene-listing tools like list_scenes.

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

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

The description implies this tool should be used when retrieving a single scene by ID, especially given the required sceneID parameter. However, it does not explicitly mention when to prefer this over list_scenes or other sibling tools, nor does it state any exclusions or 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 already mark the tool as read-only, idempotent, and non-destructive. The description adds useful behavioral detail beyond that: pagination, presigned URL contents, structured 'Comic 4' arrays, optional camera data, and the instruction to preserve null slots. It does not contradict the annotations; it only lacks potential details like URL expiry or auth behavior.

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

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

The description is front-loaded with the core purpose, then efficiently packs in return format and key behavioral caveats. Every sentence adds information: pagination, presigned URLs, array structure, null handling, and the comparison with get_motion. There is 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?

There is no output schema, so the description appropriately compensates by detailing what the response contains: motion generation records, presigned URLs, per-person arrays, camera, and null-slot preservation. Combined with the fully documented parameters and annotations, an agent has enough context to call 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 100%, so the schema already explains batchID, limit, and nextToken adequately. The description does not add parameter-level semantics beyond reinforcing the batch-specific scope and paginated nature, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Retrieves a paginated list of motion generations for a specific batch.' It also clarifies the output (motion generation records, presigned URLs, BVH files, preview videos) and explicitly distinguishes itself from get_motion, so an agent can tell this tool apart from similar 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 clearly states when to use this tool ('for a specific batch') and gives an explicit when-not: 'get_motion does not replace this complete batch listing.' This is strong routing guidance for an agent deciding between list_batch_motions and get_motion.

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 description doesn't need to repeat safety. It adds useful context by noting the scope is limited to the authenticated service account and that presigned URLs are included in the response, but it omits details like pagination behavior or sorting semantics, which are only hinted at in parameters.

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

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

The description is two concise sentences with no redundant words. The core action and scope come first, and the presigned URL note is placed second. Every sentence contributes value, making it well-structured and efficient.

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 list operation with no required parameters and full annotations, the description covers the essential purpose and a key response feature (presigned URLs). Pagination and sorting are implied by parameters, and the lack of an output schema isn't critical here given the straightforward list nature. It is nearly complete, though it could explicitly mention pagination or the returned character fields.

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% for all three parameters (limit, nextToken, sortAscending), so the schema already handles parameter documentation. The description adds no further meaning about these parameters; this matches the baseline for high 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's first sentence uses the specific verb 'Retrieves' with the resource 'a list of characters', clearly distinguishing this from the sibling get_character tool. It also names the scope ('available to the authenticated service account') and mentions presigned URLs, which adds a meaningful resource detail.

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 provides no guidance on when to use this tool versus alternatives like get_character or list_scenes. It implies a list operation through the tool name, but there is no explicit context, exclusions, or mention of sibling tools that could help an agent choose correctly.

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, and destructiveHint=false, covering the safety profile. The description adds pagination, service-account scoping, and default sort order, which is useful context but does not reveal deeper behaviors like rate limits or response structure.

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 no filler; the action, scope, pagination, and ordering are all clearly stated. Every sentence contributes meaningful information without redundancy.

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

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

For a simple read-only list operation with fully documented parameters and strong annotations, the description covers purpose, scope, pagination, and sorting. It could mention that nextToken continues previous results, but the schema already defines it, so no critical gap remains.

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 limit, nextToken, and sortAscending are fully documented in the schema. The description adds the default ordering context ('newest first by default'), which complements but does not replace the schema's parameter information.

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 ('retrieves') and resource ('motion generations'), and adds scope ('authenticated service account') and pagination/sorting details. It does not explicitly differentiate from siblings like search_motions or list_batch_motions, but the core operation 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?

No guidance is given on when to use this tool versus alternatives such as search_motions or list_batch_motions. There is no mention of filtering capabilities, exclusions, or conditions that would select this tool over others.

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 (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the description only needs to add behavioral context. It adds the scoping detail of the authenticated service account, but does not mention pagination, sorting, or response format.

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 the verb, resource, and scope efficiently, which is entirely appropriate for a simple list operation.

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 does not describe what fields a scene contains or how results are returned. The input side is well-covered by the schema, but an agent may be left uncertain about the response structure for this list operation.

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

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

Schema description coverage is 100%, with all three optional parameters (limit, nextToken, sortAscending) documented in the input schema. The description adds no additional parameter meaning, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Retrieves') and resource ('scenes'), and adds a clear scope ('available to the authenticated service account'). This makes it immediately distinguishable from siblings like get_scene (singular retrieval) and search_motions (searching a different resource).

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

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

No explicit guidance is given about when to use this tool instead of alternatives such as get_scene, search_motions, or list_motions. Usage is only implied by the plural resource name and straightforward list semantics, with no exclusions or conditions.

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 convey that this is read-only, idempotent, and non-destructive. The description adds a useful detail about the return payload ('paginated results with motion items and category aggregation information'), which goes slightly beyond the annotations, but it does not disclose deeper behavior such as default ordering, filter combination logic, or pagination token usage, though some of that is covered by 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?

The description is two sentences with no filler. The main action and filter capabilities are front-loaded, and the return summary is included without unnecessary elaboration.

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

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

For a read-only search tool, the description is reasonably complete: all six parameters have schema documentation, the safety profile is covered by annotations, and the return shape is summarized despite the lack of an output schema. It could be more complete by explaining the relationship to list_motions or clarifying what 'category aggregation information' means, but the core information needed to call it 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 description coverage is 100%, so the description does not need to repeat parameter details. It does mention the filter dimensions (category, subcategory, tags, search term) which aligns with the schema, but it adds no new meaning beyond what the schema already 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 ('Searches'), identifies the resource ('motion library'), and states the main capabilities: optional filtering and pagination. It is clear, but it does not explicitly call out how it differs from the sibling list_motions tool, so it stops short of full differentiation.

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

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

The description implies this tool is for filtering the motion library by category, subcategory, tags, or text, and for paginating results. However, it gives no explicit guidance on when to use search_motions instead of list_motions or another sibling, and it does not state any exclusions or alternatives.

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