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

Annotations already declare readOnlyHint=false, openWorldHint=true, destructiveHint=false and idempotentHint=false, so the safety profile is covered structurally. The description still adds real operational detail the annotations don't: a 15-minute single-file token that must not be shared, retry-while-valid vs. re-call-after-expiry, nonzero exit on HTTP errors, success printing a verified ready artifact, and 'Does not start compute.' That is strong added context, but the description is thin on what the upload itself mutates (project scoping, duplicate-name handling) and leans on the return value for verification.

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?

No filler sentences — the token rules, retry behavior, sibling routing and per-parameter advice all earn their place. The ordering is somewhat jumbled, however, with sibling routing and unit-handling mixed into the same dense block as parameter guidance, making it harder to scan than a clean purpose → workflow → alternatives → parameters layout.

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?

An output schema exists, so the description needn't explain return values, and it still flags the important one (success prints the verified ready artifact). For an 8-parameter, open-world write tool it covers workflow, expiry, retry, and unit ambiguity, but leaves project_id and request_id entirely unexplained in both schema and description.

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 only 38% across 8 parameters, so the description has to compensate, and it does for the semantically risky ones: sha256/size_bytes should be supplied only if already known and only together to enforce or reuse a verified upload, coordinate_units is normally omitted, engineering_context should come from the request rather than the filename, and expected_length_mm only when known. filename, project_id and request_id get no explanation in either place, which keeps this below a 5.

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 (upload an STL/STEP/STP/3MF file) plus the crucial scoping condition 'from a machine where you can run commands ... without the file passing through the model.' That condition alone distinguishes it from open_surface_upload and import_surface_attachment without opening either schema.

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 explicit routing rules: use import_surface_attachment for a host attachment, open_surface_upload when there is no command access, reuse a known ready artifact first, and reconstruct_cad for 3MF. It also states when to omit optional parameters and when to ask for clarification on units. The only soft spot is that 'Use reconstruct_cad for 3MF' sits next to 3MF being an accepted upload format, which takes a moment to parse as a post-upload step.

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