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

Annotations give the agent the read/write safety profile, and the description adds real substance beyond them: the two-step nature, that the asset sits in PROCESSING until complete_asset_upload, and the exact return payload (asset_id, upload_url, method, headers). It stops short of the operational details a PUT flow usually needs — whether upload_url expires, what error surfaces when the PUT fails or the size/content-type limits are violated, and whether an abandoned upload must be cleaned up.

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?

Three sentences, zero filler: what it does and returns first, the alternative second, and the scoping rule last. The most decision-relevant fact (two-step, use upload_asset in conversation) is front-loaded.

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 takes on the return-value burden and discharges it by naming the three returned fields and the required method/headers. For a two-step write tool the remaining gaps are modest: upload_url lifetime, failure handling, and cleanup of an abandoned upload are unstated, though none blocks a first correct call.

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%, with descriptions on all six properties including enum values and the 10 MB bound, so the schema carries parameter meaning on its own. The description restates only the space_id override behavior, which the schema already explains in fuller detail (pattern, default, GROWOMAT_SPACE_ID fallback). It adds no parameter guidance the schema lacks, so baseline 3 applies.

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 ('Start a two-step upload') plus the caller profile ('a file you can PUT yourself — a script with the file on disk'), which cleanly separates it from upload_asset and create_asset. It also names the lifecycle dependency on complete_asset_upload, so an agent understands this is step one, not the whole operation.

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 an explicit when-to-use condition (you have bytes on disk and can issue a PUT) and an explicit when-not/alternative ('In a conversation, use upload_asset instead'). It also names set_active_space as the way to change scope and explains the per-call space_id override, so routing and scoping decisions need no inference.

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