project_import_midi

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

No annotations are provided, so the description carries the behavioral disclosure burden. It clearly states the main action, but does not mention resulting project state, whether existing tracks are preserved, failure behavior on invalid paths, or what the tool returns.

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 description is compact and front-loaded with the action, followed by a minimal and clear parameter explanation. Every sentence contributes necessary information with no filler.

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 tool with one parameter and no output schema, the description is largely complete: it names the target project, the file type, and the required path semantics. It could be slightly stronger by noting the expected result, such as tracks being created, but the essential calling context is present.

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 only the parameter name and type, so the description's 'Absolute path to the MIDI file (.mid, .midi)' adds crucial semantics: it specifies the path format and accepted file extensions. For a single-parameter tool, this fully compensates for the schema's 0% description coverage.

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 states a specific verb and resource: 'Import a MIDI file into the current project.' The file type 'MIDI' and target 'current project' clearly distinguish this from sibling tools like project_import_audio and raw_import_audio.

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 usage context is clear: use this tool when a MIDI file needs to be imported into the current project. However, it does not explicitly name alternatives or state when not to use it, such as for audio imports.

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