list_batch_motions

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.