figcraft_open_file

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

No annotations are supplied, so the description carries the full load. It does disclose a real behavioral trait — the file lands in the active tab rather than a new one, and which formats are accepted — but it stays silent on side effects (does opening replace the current tab's contents?), failure modes for missing/unsupported files, and the GUI prerequisite.

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 well-formed sentence with the action front-loaded and no filler. It is efficient, though the format list crowds out the routing and prerequisite information an agent actually needs before calling it.

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 one-parameter tool this covers the core action, but with no annotations and no output schema the description should say what opening returns (e.g. a document handle needed by sibling tools like inspect_document or set_properties) and confirm the GUI prerequisite. Those gaps leave the agent guessing about follow-up calls.

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 filePath parameter is already documented in the schema. The description still adds value by enumerating the file types filePath will accept, telling the agent what inputs are valid beyond the plain 'path to open' schema text.

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 gives a specific verb and resource ('Buka berkas desain') and adds scope detail: the target is the active tab in the FigCraft GUI, plus an enumerated list of accepted formats (.figcraft, .json, .fig, .sketch, .svg, images). It does not, however, differentiate itself from the sibling figcraft_create_and_open, so an agent must infer that this one only opens existing files.

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?

Usage is only implied: opening an existing design file as opposed to creating one. The description never states when to prefer this over figcraft_create_and_open, nor any precondition such as the GUI needing to be running (a sibling figcraft_ensure_gui exists, which suggests a prerequisite worth mentioning).

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