project_import_audio

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

No annotations are provided, so the description carries the behavioral burden. It does disclose the main side effect ('Creates a new track') and supported formats, which goes beyond the schema. However, it does not mention project-open prerequisites, failure behavior, or whether the file is copied/linked, leaving those behaviors implicit.

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?

Two short sentences plus a single args line; the essential purpose and side effect are front-loaded, and no words are wasted. The format examples are placed exactly where they are useful.

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 import tool this is largely sufficient: an agent knows what to pass and what will happen. It falls short only in not stating explicit prerequisites (an open project) or what the tool returns/does on failure, which would matter more without annotations or output schema.

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 input schema only gives `path` as a string with no explanation, and schema description coverage is 0%. The description compensates by specifying that the path must be absolute and enumerating common audio formats (wav, mp3, ogg, flac, etc.), giving the agent concrete invocation guidance.

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 action ('Import an audio file'), the target resource ('current project'), and the key side effect ('Creates a new track'), so an agent can distinguish it from unrelated edit/effect/transport tools. It does not explicitly differentiate from the sibling raw_import_audio, though the programmatic path argument and project_ prefix imply the difference.

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 implies the use case—bring an audio file into the current project as a new track—but gives no explicit guidance about when to choose this over raw_import_audio or project_import_midi, and no 'when not to use' information. This is enough for obvious import requests but not for routing among similar import siblings.

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