Download a creation

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses critical behaviors: full-res writes to disk with automatic extension, preview is downscaled and safe for context window, and path safety constraint with TWODAI_ALLOW_ANY_PATH override. It also clarifies that the tool never injects full bytes into the context, which is important for the agent. No annotation contradiction 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 sentences, each packed with distinct, necessary information: purpose, mode behavior, and path constraint. It is front-loaded and concise without unnecessary elaboration. Every sentence earns its place, making it highly efficient for an AI agent to parse.

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 there is no output schema, the description adequately explains the return values for both modes (path or inline preview). It also covers the environment variable override and the dual-ID input context. While it does not detail error cases, it provides enough operational context for the agent to invoke the tool correctly, making it complete for the tool's complexity.

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 provides 100% coverage for all three parameters, so the baseline is 3. The description adds extra meaning by explaining the semantics of savePath (full-resolution, extension appended, returns path) and the behavior when savePath is absent (preview image). This goes beyond the schema's bare field descriptions, though it does not add new details for cdnId or creationId 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 begins with a specific verb+resource ('Fetch a creation's media') and then immediately contrasts two clear modes: saving full-resolution to disk with savePath vs. returning a downscaled preview inline. This makes the tool's purpose unambiguous and distinguishes it from siblings like list_creations or browse_feed, which handle discovery rather than media retrieval.

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 context on when to use each mode (savePath for full-res file, no savePath for inline preview), which serves as usage guidance. It does not explicitly name alternative tools or state when not to use the tool, but the conditional usage is clear enough that the agent can decide correctly. There are no exclusions or conflicting guidance.

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