save_project

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

With no annotations, the description carries the full burden and largely succeeds. It discloses default-path behavior, compression format selection, and importantly warns that writing compressed data into a .mmp file breaks LMMS and other tools. It does not mention overwrite behavior or permissions, but the format warning is strong for a write operation.

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?

The purpose is front-loaded in the first sentence, and the Args section is compact and well-structured. The parameter explanations and warning are all useful, though the two separate default-directory cases in the path description are slightly redundant and could be condensed.

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?

The description covers both parameters thoroughly and includes a practical failure warning, while the presence of an output schema handles return value documentation. It omits minor context such as whether existing files are overwritten and whether a project must already be open, but these are largely inferable from the tool name and sibling set.

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?

The schema provides zero parameter descriptions, and the tool description fully compensates. It explains path defaulting to the projects directory, filename-only handling, and the compressed parameter's True/False/None semantics including the extension-based fallback and the .mmp plain-XML rule.

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 opening sentence 'Save the current LMMS project to a file' states a specific verb, resource, and file target, making the tool's purpose immediately clear. It is distinct from sibling tools like load_project, create_project, and render_project because it explicitly refers to saving the project file itself.

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?

The description explains how the parameters behave but gives no explicit guidance on when to choose save_project over alternatives. It does not mention exclusions, prerequisites, or contrast with related operations like load_project or render_project, leaving the agent to infer usage context.

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