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

The description goes well beyond the sparse annotations (readOnlyHint=false, destructiveHint=false). It discloses that Tango downloads and stores fetch_url files, that external_url is not copied, that invalid signatures reject the call with nothing stored, and that delegated workers are signed for automatically. It also explains the subtle attribution behavior: if you don't own the worker, attribution is dropped rather than misrecorded.

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 dense but each sentence earns its place, covering purpose, content modes, attribution, and signing behavior. It is front-loaded with the working-agreement context. The only minor issue is that it reads as one long block; bulleted mode routing would improve scannability without adding length.

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 tool with 15 parameters and multiple content modes, the description covers nearly everything an agent needs: all storage modes, size limits, attribution, signing, and the relation to complete_task. The main gap is that it does not describe the success response or returned artifact id, and it does not mention evidence_kind selection beyond a passing reference, though the schema documents that 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 coverage is 100%, so the baseline is 3, but the description adds significant meaning: size limits for content_base64 vs fetch_url, the role of upload_token as a finalize step after create_artifact_upload, the distinction between stored content and merely recorded external links, and the JCS-canonical payload requirement for worker_signature. These semantics are not inferable from the schema alone.

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 precise verb-resource pair ('Attach every concrete output ... as an artifact') and clearly scopes what qualifies: notes, drafts, results, files, links. It also differentiates the tool from chat-oriented siblings by saying the artifact should be 'part of the task record, not just chat', and from create_artifact_upload by describing the upload-token handoff.

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 mode routing: content_base64 for files up to ~6 MB, fetch_url for hosted files up to 50 MB, create_artifact_upload plus upload_token for large files, content for inline text, and external_url for links only recorded. It also tells the agent when attribution logic changes (lease active vs acting_worker_id) and directs artifact ids into complete_task's evidence_artifact_ids.

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