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

With readOnlyHint and openWorldHint already present, the description adds value by specifying the exact UI path (Astra → Settings → Integrations → Local API) and what the report covers. It doesn't contradict annotations and provides actionable diagnostic context, though it doesn't detail output format.

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, front-loaded with the primary purpose, then a concrete use case. No redundant information, every sentence 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?

Given no parameters, read-only annotations, and a simple reporting focus, the description covers the purpose, usage scenario, and scope of the report. It's complete for an agent to select and invoke 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?

The tool has 0 parameters, so the baseline is 4. The description adds meaning by outlining what the report includes (scopes, features, limits), which is useful even without parameters.

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 ('Report') and resource ('Astra Companion API scopes, features, and current limits'). It clearly distinguishes from sibling tools by focusing on capabilities and diagnostics rather than playback control.

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 explicit when-to-use guidance: 'Useful for diagnosing a permission error: if a tool returns insufficient_scope...'. This clearly indicates the diagnostic context and implies when alternatives (the control tools) would be used instead.

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?

Beyond annotations (readOnlyHint=false, etc.), the description discloses that the tool accepts commands asynchronously and waits briefly to report the resulting state. This is a valuable behavioral detail that annotations do not cover, providing insight into how the tool executes and what it 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 core purpose. Each sentence adds distinct information (actions, argument requirements, async behavior, alternative tool usage) without redundancy or unnecessary detail. It is appropriately sized for a multi-action control tool.

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 covers the essential operational context: full action list, conditional parameters, asynchronous execution with state reporting, and a clear alternative path for starting specific media. For a tool with 6 parameters and 10 actions, this is comprehensive.

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%, and each parameter already has a description. The description adds value by mapping each action to its required argument (e.g., 'seek needs positionSeconds'), which consolidates conditional requirements in one place. It also reinforces the volume range (0-1), though that's already in the schema.

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 purpose: controlling playback in Astra with a list of 10 specific actions (play, pause, stop, etc.). It distinguishes itself from sibling tools like astra_play by explicitly noting 'To start a specific track or album instead, use astra_search then astra_play.'

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?

Provides explicit usage context: this tool controls current playback, and for starting specific media it directs the agent to use astra_search then astra_play. It also explains the asynchronous behavior ('Astra accepts commands asynchronously; this tool waits briefly and reports the state it actually landed on'), which guides expectations for invocation.

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?

The annotations mark the tool as non-read-only, non-idempotent, and non-destructive, but the description adds valuable behavioral details: it is non-interrupting, refs are opaque signed strings that must be passed through verbatim, and a stale ref can return 404. This goes beyond the annotations by explaining the opaque ref protocol and failure mode, giving the agent important operational guidance.

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 three sentences, front-loaded with the core action and key benefit, followed by parameter-specific guidance and ref handling. Every sentence earns its place, with no redundancy or fluff. It is concise yet information-dense, ideal for quick comprehension by an agent.

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 two-parameter queue-addition tool with no output schema, the description fully covers what the tool does, how to use each parameter, how to handle refs, and the potential 404 error. Combined with the annotations, an agent has complete information to select and invoke the tool correctly without ambiguity.

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 already covers both parameters with 100% description coverage, including the enum for position and a detailed explanation for targetRef. The description adds semantic richness by clarifying that the ref can represent a track, album, artist, or playlist, and by explaining how 'next' vs 'end' affects playback order. This enriches the schema's baseline and helps the agent understand the domain meaning.

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 opens with a specific verb and resource: 'Add a track, album, artist, or playlist to the Astra queue.' It also differentiates from siblings by noting 'without interrupting what is playing,' which clearly distinguishes it from immediate-play tools like astra_play. The purpose is unambiguous and directly tied to the tool name.

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 for when to use the tool (to add to the queue without interrupting current playback) and gives explicit positional guidance: 'Use position "next" to play it after the current track, or "end" to append.' It does not explicitly name alternative tools (e.g., astra_play), but the phrase 'without interrupting what is playing' implies the alternative is immediate playback. This is clear context without explicit exclusions.

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 mark this as readOnly and openWorld, but the description adds meaningful behavioral detail beyond those: the live event stream backing, the cheapness of calling, and the ability to pass the returned ref to astra_set_favorite or astra_playlist. This enriches understanding of the tool's behavior without contradicting 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?

The description is three sentences, front-loaded with the primary purpose, and every sentence adds distinct value: what is returned, why it is cheap, and how the result can be used downstream. There is no redundant or filler content.

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 zero-parameter, read-only state getter with an output schema and annotations, the description is contextually complete. It specifies the return contents and integration potential, leaving no significant gaps for an agent to select or invoke the tool 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?

With zero parameters, the description is not required to elaborate on parameter meaning. The baseline score of 4 applies, and the description does add value by enumerating what the returned state includes, which compensates for the absence of 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 uses a specific verb ('Get') with a clear resource ('current playback state of the Astra music player') and enumerates the exact fields returned. It distinguishes itself from sibling tools like astra_control or astra_play by focusing on read-only state observation.

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 clearly implies when to use this tool: whenever current playback state is needed. It adds practical usage context ('Served from a live event stream when connected, so it is cheap to call') and explains how the returned ref connects to other tools, though it does not explicitly list when-not-to-use or alternatives.

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?

Beyond annotations, the description discloses that the window is brought to front, that playback is not started, that refs can go stale and return 404, and that refs should never be parsed or edited. This adds significant behavioral context not captured by the 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?

The description is front-loaded with the main purpose and stays concise. All sentences serve a purpose—covering behavior, parameter handling, and error cases. No redundancy or fluff.

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 that this is a simple navigation tool with one parameter and no output schema, the description covers all essential aspects: what it does, what it doesn't do, how to handle the parameter, and a potential error case. It is contextually 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 coverage is 100%, including a detailed description of targetRef. The tool description adds extra guidance about passing refs verbatim and the risk of staleness, which is valuable beyond the schema. Baseline 3 raised due to this additional semantic 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?

The description clearly states a specific action: 'Bring the Astra window to the front and navigate to a track, album, artist, or playlist.' It also distinguishes from siblings by noting 'it does not start playback,' setting it apart from playback tools like astra_play.

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 context for when to use the tool: to show a target without starting playback. It explicitly states it takes a ref from astra_search, which implies a prerequisite. However, it doesn't explicitly name alternative tools or when-not-to-use exclusions beyond playback.

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 flag destructiveHint=true and readOnlyHint=false, but the description adds crucial specifics: it replaces the current queue (what gets destroyed), explains refs are opaque signed strings that must be passed verbatim, and discloses that a ref can go stale and return a 404. This is meaningful behavioral context beyond the basic annotation flags.

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 four sentences, each earning its place: the action, the prerequisite, and the alternative. It is front-loaded with the main purpose and avoids redundant phrasing.

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 tool with no output schema, the description covers prerequisites (astra_search), error conditions (stale ref 404), side effects (queue replacement), and the alternative for resuming (astra_control). This is complete enough for an agent to select and invoke it correctly without further assumptions.

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% and the parameter description in the schema fully explains targetRef, including the opaque-string caveat and staleness risk. The description repeats the same semantics without adding new parameter details, so per the baseline for high schema coverage, a 3 is appropriate.

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 opens with a specific action: 'Start playing a track, album, artist, or playlist in Astra, replacing the current queue.' It names the resource (Astra content), the operation (play), and the side effect (replaces current queue), which clearly distinguishes it from siblings like astra_enqueue (adds) and astra_control (resumes).

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?

Explicitly instructs to call astra_search first to convert a name into a ref, and explicitly names the alternative for resuming already-loaded content: 'use astra_control with action "play" instead.' This provides clear when-to-use and when-not-to-use guidance.

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?

The annotations only signal mutating, open-world, non-idempotent behavior. The description goes far beyond by disclosing that refs are opaque signed strings that must be passed verbatim, that stale refs yield 404, that only locally owned normal playlists are editable, and that deletion is impossible. This is rich behavioral context with no contradictions.

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 front-loaded with a clear first-sentence summary, then efficiently lists required parameters per action, followed by essential cross-tool references and failure modes. Every sentence is informational and earns its place; there is no filler or redundant explanation.

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 (six parameters, five actions, no output schema, sparse annotations), the description covers all necessary operational context: how to source refs, what causes 404, what playlist types reject edits, and the absence of deletion. It is sufficiently complete for an agent to invoke correctly without further clarification.

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?

While the schema already covers all parameters (100% coverage), the description adds crucial per-action requirements ('create needs name', 'rename needs ref and name', etc.), the automatic batching of >100 trackRefs, and the rule to never parse or edit refs. These semantics are not present in the schema and significantly improve correct invocation.

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 opens with a precise and specific verb-resource pairing: 'Create a playlist in Astra, rename one, or add / remove / reorder its tracks.' It enumerates all supported actions and clearly distinguishes this playlist-focused tool from sibling queue-editing tools like astra_queue_edit.

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 tells the agent where to obtain refs (astra_search), explicitly excludes mirrored/dynamic playlists with a concrete error code, and explicitly states that playlist deletion is not available. These are direct when-to-use and when-not-to-use directives with an alternative source, exceeding the minimum guidance.

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?

Beyond the readOnlyHint annotation, the description adds crucial behavioral details: the tool is served from the live event stream when connected, and Astra only publishes the first 200 queue entries, truncating longer queues. These are valuable insights not covered by annotations, enhancing the agent's understanding of tool behavior.

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 at three sentences, with each sentence serving a distinct purpose: stating the core function, hinting at parameter/identifier usage, and disclosing an important limitation. It is front-loaded with the primary action and has no redundant 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 simple read-only tool with one optional parameter and no output schema, this description is exceptionally complete. It covers the purpose, behavior, live-streaming aspect, truncation limitation, and cross-reference to the editing sibling, leaving no significant gaps for an agent to infer.

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 already fully documents the single 'limit' parameter (including default, min, max, and description). The description adds some context by explaining why the maximum is 200, but this is supplemental rather than required. With 100% schema coverage, the baseline score of 3 is appropriate.

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: 'List the tracks in the Astra play queue, in order, with the currently playing one marked.' It uses a specific verb ('List') and resource ('Astra play queue'), and distinguishes itself from siblings by explicitly directing users to astra_queue_edit for modifications.

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 for when to use the tool (viewing the queue) and even gives an alternative for editing ('pass that to astra_queue_edit'). However, it does not explicitly state any exclusions or contrast with similar read tools like astra_now_playing, so it slightly misses the 'when-not' guidance for 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 set destructiveHint=true and readOnlyHint=false, but the description adds critical context: 'clear' empties the upcoming queue without stopping the current track, and the currently playing item cannot be moved or removed, returning queue_item_not_found. This goes beyond the annotation flags and helps the agent predict side effects.

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, and every sentence carries distinct information: action semantics, param requirements, ID source, edge-case error, and alternative tool. 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?

Despite having no output schema, the tool is a mutation with three actions, and the description covers all actionable cases: how to perform each action, the source of IDs, the sole error case, and the alternative for adding. Annotations cover safety flags, so nothing essential 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?

Schema coverage is 100% with per-parameter descriptions, so baseline is 3. The description adds value by mapping each action to required parameters ('move' needs queueItemId and a 0-based position; 'remove' needs queueItemId) and by specifying that queueItemId comes from astra_queue, a cross-tool reference not present in the schema.

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 opens with 'Reorder or trim the Astra play queue', a specific verb+resource statement, and enumerates three actions (move/remove/clear) that map to the enum. It also distinguishes itself from astra_enqueue for adding and points to astra_queue for IDs, removing ambiguity with siblings.

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 explicitly tells the agent when to use this tool ('Reorder or trim the play queue') and when not to: 'To add tracks instead, use astra_enqueue.' It also gives a prerequisite: 'Get queue item ids from astra_queue.' This is clear usage guidance with an alternative tool named.

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?

Beyond the readOnlyHint annotation, the description discloses search bounds (non-empty query, max 50 results, no pagination, no catalog listing). It also says results are 'opaque refs,' telling the agent not to expect human-readable metadata in the output.

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 three sentences, front-loaded with the core action, then value-added context (entry-point, bounds) and follow-up. No filler 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?

The description provides essential workflow context (only way to resolve names), query constraints, and next-step tools. As a read-only search operation with robust annotations and schema coverage, it is complete without needing a return-value 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?

Schema coverage is 100%, so the schema already fully describes q, limit, and types. The description mentions 'non-empty query' and 'at most 50 results,' mirroring the schema's minLength and maximum, adding no new semantics. The phrase 'by name' reinforces q's purpose, but schema already says 'Search text.'

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 uses the specific verb 'search' with a clear resource ('local Astra music library') and output ('opaque refs'). It explicitly states this is the only way to get refs from names, differentiating it from sibling tools that require refs.

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 says 'This is the entry point for almost everything' and provides explicit follow-up guidance ('Follow up with astra_play, astra_enqueue, or astra_open'). It also excludes alternatives: 'nothing else in this server accepts a title or artist name, only a ref from here.'

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?

Beyond annotations, the description adds the behavioral nuance that the operation sets an explicit state (reinforcing idempotency) and warns that refs can go stale and return 404, providing a failure mode not present in the 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?

The description is three sentences, front-loaded with the core purpose, and each sentence adds value—state-setting behavior, input source, and ref handling. No filler or 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?

With only two documented parameters, rich schema descriptions, and annotations covering idempotency and safety, the description fully covers the tool's behavior, input requirements, and failure mode. No output schema is needed for this simple action, but the description is sufficient 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 coverage is 100% with both parameters fully described (trackRef as opaque string and favorite as boolean). The description largely repeats this information without adding new parameter-level meaning, so the baseline of 3 is appropriate.

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 'Mark or unmark a track as a favorite in the Astra library' with a specific verb and resource, and it distinguishes itself by noting it sets an explicit state rather than toggling, which differentiates it from other track-related operations.

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 explicit guidance on where to obtain a valid trackRef (from astra_search or astra_now_playing) and instructs to pass refs verbatim without parsing or inventing. It does not explicitly exclude alternative tools, but the input-source guidance gives clear context for use.

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