get_preview_url

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

With no annotations, the description carries the burden. It discloses an important behavioral constraint: the URL is for auditioning only and any project use requires a license. However, it doesn't describe other behavioral aspects like whether the URL expires, rate limits, or authentication requirements. This is useful but incomplete.

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 two concise sentences, front-loaded with the primary use case and followed by an important license caveat. Every sentence earns its place with no redundancy.

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?

Given the tool's simplicity (one required parameter, no output schema, no annotations), the description provides sufficient context: when to use it and the legal restriction. Missing details like URL expiration or authentication are minor for a preview URL endpoint, but could be helpful.

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 description coverage is 0%, and there is 1 parameter (track_id). The description doesn't explain the parameter at all. However, the parameter is straightforward (an integer ID) and the schema includes a minimum constraint. The description adds no parameter-specific semantics, but baseline for 0 params is 4; with 1 param and no coverage, a 3 is appropriate because the parameter is simple and self-explanatory.

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 clearly states the purpose: getting a preview URL for auditioning a track. It distinguishes from siblings like get_track (metadata) and quote_license (pricing) by focusing on auditioning. However, it doesn't explicitly name the resource 'preview URL' in a verb+resource format, though the name already does that.

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 provides clear context: 'when the user wants to listen to (audition) a track.' It also clarifies the usage restriction: 'The URL is for auditioning only; any use of the track in a project requires a license.' It doesn't mention alternatives like get_track for other purposes, but the usage condition is explicit.

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