Artyfile Music Licensing

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

With no annotations, the description carries the full burden of behavioral disclosure. It explicitly states that the agent never completes payment (EU PSD2), the user must approve in a browser, the result includes a URL and publicId, and the session expires after 1 hour. This is highly transparent and prevents misinterpretation.

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 concise and well-structured, with the main action in the first sentence and critical behavioral details in the second. Every sentence adds value without unnecessary 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?

Given the tool's complexity (5 params, no output schema, no annotations), the description covers the essential return values (URL and publicId) and the expiry behavior. It could potentially explain error scenarios or what happens after payment, but the presence of sibling tools like get_order_status covers that gap. It is sufficiently complete for an agent to use it correctly.

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 high (80%), so the baseline is 3. The description does not add parameter-level semantics beyond the schema, but it does clarify the overall purpose (one track) and reservation. It doesn't compensate for the missing 'locale' description, but that parameter is an enum with defaults, so the gap is minor.

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 specific action ('Create a checkout for one track') and the resource involved. It distinguishes itself from sibling tools by focusing on creating a payment checkout rather than searching or retrieving data.

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 about the checkout flow, including that the user must approve payment and that the session expires. It does not explicitly name alternatives or exclusion criteria, but the context effectively implies when this tool should be used (for initiating a purchase).

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

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

With no annotations, the description adds meaningful details: the WAV link is re-issuable anytime and requires no cookies. This goes beyond generic get behavior, though it doesn't mention potential failure modes or auth for other documents.

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?

A single, well-structured sentence that front-loads the purpose and adds specific details without fluff. Every word earns its place.

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?

Despite no output schema, the description enumerates the returned URL types and highlights the re-issuable nature of the WAV link. It lacks return format details, but for a simple single-parameter tool, this is reasonably complete.

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 has only publicId, but the description never explains that publicId is the order identifier. With 0% schema coverage, the description should compensate by explicitly linking this parameter to the paid order context, which it fails to do.

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 tool returns download and document URLs for a paid order, specifying the exact resources (WAV, PDF invoice, license certificate). This distinguishes it from sibling tools like search_tracks or get_order_status.

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 explicitly limits usage to paid orders, which is useful context. It doesn't name alternatives or exclusions, but the paid-order precondition is clear enough for an agent to select this tool appropriately.

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

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

With no annotations provided, the description carries the burden of disclosure. It explains that the output is machine-readable and enumerates the included elements (tiers, pricing, restrictions, links). This adds meaningful behavioral context beyond a simple 'get terms' statement, though it does not specify return format or whether any side effects occur.

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 sentences, front-loaded with the primary purpose ('Machine-readable summary of the Artyfile licence tiers'), then adds concrete details. Every word contributes value; 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?

For a simple no-parameter information tool, the description is fully complete. It states what is returned, specific content (tiers, pricing, restrictions, links), and the machine-readable nature. No additional context is necessary given the tool's simplicity and lack of 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 tool has zero parameters, so the baseline is 4. The description does not need to explain parameter meanings, and none are missing.

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 identifies the tool as providing a machine-readable summary of license tiers, with specific details like pricing and restrictions. It is distinct from sibling tools which handle checkout, downloads, order status, and search.

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 that this tool is used for retrieving license terms, but does not explicitly state when to prefer it over alternatives or provide exclusion criteria. The intended use is inferred from the name and content, but no direct guidance is given.

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

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

With no annotations, the description carries the full burden. It discloses the payload contents when status is 'paid' (downloadUrl, invoiceUrl, certificateUrl), the polling interval, and the expiration policy. This adds meaningful behavioral context beyond the schema, though it stops short of describing error responses or other statuses.

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 sentences, directly front-loaded with the tool's purpose and essential operational details. No wasted words; every clause adds value.

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 polling tool with no output schema, the description covers the main behavioral aspects: URL payloads on success, polling interval, and expiration. It does not mention error handling or invalid publicId responses, but the core usage is adequately specified.

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 the description only mentions 'publicId' without adding context about its origin or format beyond what the schema already provides (string, 6-64 chars). The parameter is simple, but the description does not compensate for the lack of schema-level explanations.

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 tool's function: 'Poll an order by publicId.' It specifies the resource (order) and the action (poll), and distinguishes itself from sibling tools like get_download_link or get_track by focusing on order status and the associated URLs returned once paid.

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?

It provides clear usage context: poll after creating a checkout, poll every 15 seconds, and treat pending orders older than 1 hour as expired. It does not explicitly name alternatives or when not to use, but the polling cadence and expiration rules give adequate guidance for typical use.

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

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

No annotations are provided, so the description must carry the burden. It states the tool returns full details but does not mention error handling, whether the operation is read-only, or any rate limits. The listed fields give some transparency but not deeper behavioral context.

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 a single sentence with a colon-separated list, front-loading the purpose ('Full details for one track') and using no redundant words.

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 single-parameter get tool, the description adequately covers purpose, identifier options, and returned content categories. The lack of an output schema is partially mitigated by the explicit list of detail types, though error scenarios are not addressed.

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 covers the single parameter with description 'productId (from search_tracks) or the track slug', which already adds rich context. The main description reinforces this by mentioning both identifiers, exceeding baseline schema 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?

Clearly states the tool retrieves 'Full details for one track' using either productId or slug, and enumerates the detail categories (metadata, prices, licence scope, preview URL, human product page), distinguishing it from sibling tools like search_tracks (list) and get_license_terms (license-specific).

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?

Implies a workflow where the productId comes from search_tracks, and lists the type of details, providing contextual guidance. However, it does not explicitly state when to prefer this over alternatives (e.g., use get_license_terms for license-only info).

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

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

With no annotations, the description carries the burden of disclosing behavior. It does so by stating the tool searches, returns ranked tracks with prices, identifies productId mapping, and highlights the licenseScope caveat. It doesn't cover all possible behaviors (e.g., rate limits), but for a read-only search operation, this is solid disclosure.

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 sentences, front-loaded with the core purpose, and every sentence adds value—the first explains the tool's function and the second provides a critical usage warning. No wasted words.

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?

Despite no output schema, the description explains the key return values (ranked tracks with prices), the relationship to create_checkout, and the important licenseScope caveat. It doesn't mention default limit or pagination, but for a search tool with simple params, the coverage is sufficient for an agent to understand and invoke it correctly.

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 only 25% (only query has a description), and the description does not compensate for mood, genre, or limit. It adds no meaning beyond what the schema already provides for these parameters, and even query's description is not enhanced. The main description focuses on the catalog and results, not parameter semantics.

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 tool searches the Artyfile catalog for licensable music and returns ranked tracks with prices. It uses a specific verb ('search') and resource ('Artyfile catalog'), and distinguishes this from the sibling tools by noting the result id is the productId accepted by create_checkout.

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 usage context: it's for searching real recordings, and explicitly warns against selecting master_only Cover Editions for film/video/media projects. It doesn't explicitly say 'use this when you need to find music', but that is strongly implied and the warning about exclusions adds valuable guidance.

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