upload_file

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

With no annotations, the description carries the burden well: it discloses capability requirements ('upload', plus 'state' for import confirmation), that the operation merges rather than replaces, that it blocks up to wait_seconds on LightBurn's file_imported event, and that it reports the outcome. It does not say what happens on timeout or import failure, which is the main remaining gap for an unannotated tool.

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?

A single dense paragraph with the capability prerequisite front-loaded and no filler sentences. The format enumeration is long but functional; the sentence about waiting/reporting could have been merged less verbosely, keeping it a point shy of ideal.

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 9-parameter, zero-required mutation tool with no output schema and no annotations, the description covers prerequisites, placement semantics, payload modes, and outcome reporting. The only missing piece is failure/timeout behavior, which matters here given the blocking wait.

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 already 100%, so the baseline is 3; the description justifies a bump by explaining the interaction between parameters — x/y as a pair with mm workspace semantics, origin selecting which bounding-box point sits at the anchor with center as default, and the three mutually exclusive payload channels. It still defers to the schema for group_shapes and filename details.

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 ('Imports a file into the CURRENT project (merge), like File > Import') and enumerates supported formats, so the agent knows exactly what happens. It implicitly distinguishes itself from open_file by emphasizing that the target is the current project and that it merges rather than replaces, but it never names that alternative.

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 clear conditions: current-project import, choose path vs content vs content_base64 depending on whether the file is local or generated, and x/y only when anchoring is desired (otherwise current view center). It lacks an explicit 'use open_file instead when you want to load a project file' exclusion.

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