List Generation Tasks

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

Annotations declare readOnly/idempotent/openWorld, and the description adds substantive behavior beyond them: filtering happens after fetch so pages can be shorter than limit, iteration via next_offset/has_more, per-type requests meaning partially failed queries surface in failed_types, and the cross-surface caveat that API-created tasks never appear in the web app.

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

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

Front-loads the default behavior and type coverage, then routes alternatives and pagination caveats. Dense but every sentence carries information; the enum-heavy schema not the prose is where the bulk lies, so the description itself is appropriately sized.

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?

No output schema exists, yet the description names the key return fields an agent needs (failed_types, has_more, next_offset) and explains the pagination caveat for a list tool with 8 params. Nothing material is missing for correct invocation.

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 meaning beyond the schema: task_type names are the same as meshy_get_task_status, and task_types is merged with task_type with a documented default set. It stops short of clarifying the interaction between status/phase and limit beyond the pagination note.

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 ('List tasks') plus scope ('any status', 'merged across the types queried', 'newest first by default'). It explicitly contrasts itself with meshy_get_task_status and meshy_list_models, so an agent can distinguish it from siblings 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?

Names two alternatives with the exact conditions that select them: 'With a task_id in hand, use meshy_get_task_status instead' and 'For finished 3D models only, meshy_list_models is cheaper.' It also documents the default type set and how to reach rigging/animation/print/Creative Lab tasks.

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