Open a project

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

Annotations already declare readOnly/idempotent/openWorld, and the description reinforces this with 'Opening a file does not change it' and discloses the dual read mechanisms (JS direct vs bundled Python codec for Pivot). It also promises a return of project id plus summary. Missing: failure behavior for missing/unsupported files, minor given the read-only annotations.

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, front-loaded with the action and effect, then format support, then return value and the non-mutating guarantee. Every sentence carries distinct information; the JavaScript/Python codec detail is the only mildly implementation-flavored bit and it justifies the extension list.

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?

No output schema exists, yet the description states what is returned (project id plus a project summary), which is exactly what an agent needs to chain into later tools. It leaves unstated what happens when a project is already open, but idempotentHint covers much of that.

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 single 'path' parameter is already documented. The description nonetheless adds real meaning by enumerating the accepted extensions (.styk, .stkz, .stykmov, .piv, .stk), which tells an agent what kind of value is valid — beyond the schema's generic 'absolute or relative path'.

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 (open) and resource (StykAnimate/Pivot project file) and adds the scope detail that it 'makes it the active project' and returns a project id. The supported extension list separates it from siblings like project_close or project_describe without requiring schema inspection.

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?

Clear about the context of use — open a project file, which then becomes active and yields an id that 'later tools accept', implying this is the entry point before project_describe/layer_list. It does not explicitly name an alternative or exclusion (e.g. what to do if a project is already open or how to inspect rather than open), so it stops short of a 5.

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