Tera Studio

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, and the description goes well beyond them: data provenance (AcousticBrainz recording analyses), agreement count across analyses, BPM only when analyses agree, estimated vocal range, returned links, and explicit not-found behavior. That is rich behavioral context for a lookup tool.

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?

Four sentences, front-loaded with purpose, then usage, then parameter guidance, then failure behavior. No redundant restatement of the title or annotations; every sentence carries information.

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 an output schema existing, the description still explains the meaningful return elements (relative key, agreement count, BPM, range, links) and the not-found fallback. Combined with the fully described schema and safe-read annotations, an agent has what it needs to call this 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 100%, so the baseline is 3, but the description adds intent-level meaning: semitones is framed as 'if they want it higher or lower' for voice suitability, and title lookup is framed as identifying a song rather than a free-text query. The artist parameter is left to the schema, which already explains its disambiguation role.

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 verb and resource (look up key, tempo and vocal range of a song by title) plus the backing source (AcousticBrainz analyses in Tera Studio's list). However, it does not acknowledge the sibling find_song_key_and_tempo, which also returns tempo, or shift_song_key, which also covers transposition — so the boundary between this tool and its siblings stays blurry.

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?

Gives a clear triggering context ('when someone names a song and asks its key or tempo, or whether it suits their voice') and a secondary case for the semitones parameter. It stops short of saying when NOT to use it or naming the overlapping alternatives (find_song_key_and_tempo, shift_song_key).

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?

Annotations cover safety (readOnly, idempotent, non-destructive, closed-world), and the description adds material context beyond them: the call opens a Tera Studio tool where the user picks the file, analysis runs in-browser and the file is never uploaded, and the tool reads only the file rather than identifying or playing songs. The privacy/local-processing guarantee and the interactive file-picker flow are exactly the kind of behavior an agent cannot infer from annotations.

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?

Four sentences, each doing distinct work: what it returns, how it runs and its privacy property, when to invoke it, and its boundary against the sibling. The capability statement is front-loaded and there is no filler or restatement of the title.

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?

With an output schema present, return-value explanation is unnecessary, and the description covers the remaining essentials: trigger conditions, the interactive flow, privacy handling, and the sibling boundary. Nothing an agent needs to select and call this zero-parameter tool is missing.

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 takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description does clarify that the file is chosen by the user inside the opened tool rather than passed as an argument, which prevents an agent from expecting a file parameter.

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 verb and resource (find musical key + tempo in BPM of a song file) and even specifies the output granularity (major or minor, with relative key). It explicitly contrasts with the sibling find_song_key, so an agent can distinguish the two without opening either schema.

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?

Names concrete triggering contexts ("when someone asks what key or BPM a song is in, or wants to know before singing, mixing or practising it") and an explicit alternative with its selecting condition ("find_song_key looks up a well-known song by its title"). When-to-use, when-not, and the alternative are all present.

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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description adds real context the agent could not otherwise know: a Tera Studio UI opens for file selection, processing happens in the browser, and nothing is uploaded. That interaction and privacy model is exactly the kind of disclosure annotations cannot carry.

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 core action is front-loaded and every clause contributes (direction, limit, speed preservation, playback, local processing, parameter routing). The first sentence is dense and packs several distinct facts, but there is no filler to cut.

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?

With an output schema handling return values, one optional parameter, and rich annotations, the description covers everything an agent needs: when to invoke, how to treat the parameter, and what the user experience will be. No material gaps remain.

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 100%, so the range and negative-is-lower semantics are already documented; the description nonetheless adds a decision rule — only pass semitones when the person stated a distance, otherwise defer to the in-tool choice. The rest is largely restatement of the schema, so it sits just above baseline.

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 verb and resource — move a song up/down by up to 6 semitones, preserve speed, and play it back — which clearly separates it from the find_* siblings that only analyze. It never names those siblings, so differentiation is inferred from the verb rather than stated.

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?

"Use it when a song is too high or too low for someone" gives a concrete triggering condition, and the semitones rule ("Pass semitones if they said how far... otherwise they choose in the tool") tells the agent exactly when to supply the parameter. No explicit exclusions or named alternatives, which keeps it below a 5.

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?

Annotations already declare readOnly/idempotent/non-destructive, and the description reinforces this with 'returns steps and a link and creates nothing.' Beyond that it discloses what the person must actually do (create an account, sing ~a minute, add a song they have rights to use) and the voice-ownership restriction, which no structured field conveys.

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 and outcome are front-loaded, followed by the workflow and the exclusion. Every sentence is relevant, though the signup/sing/upload sequence is slightly more procedural detail than an agent needs before invoking.

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?

With an output schema present and full schema descriptions, the description needn't explain return values, and the annotation set covers the safety profile. It is essentially complete, only omitting any hint about what the optional inputs are for.

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 100% and all three parameters are optional with clear per-field descriptions, so the schema carries the load. The description never references language, occasion, or song_title, so it adds no meaning beyond the schema — baseline 3.

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 leads with a specific verb and outcome: explain how to hear a song in one's own voice with Tera Studio and give them the start link. It is also clearly not a music-analysis operation like the sibling find_song_key tools, so an agent can distinguish it without opening a schema.

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 gives concrete triggering intents — hear yourself sing, make a cover in your own voice, turn a song into a gift — plus an explicit exclusion: not for celebrity or other people's voices. It stops short of naming alternative tools or the case where a different path (e.g. key/tempo tools) is the right call, so it's a 4 rather than a 5.

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