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

With no annotations provided, the description fully carries the behavioral burden: it discloses pre-write refusals (empty set, ceiling, expected_count), guarantees no write on validation failure, and states the output summary categories. This goes well beyond a generic 'add tags' statement.

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?

Three sentences each carry distinct value: operation, validation rules, and result summary. There is no filler, no repetition of schema, and the core behavior is front-loaded.

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 write tool with no annotations and a 0%-coverage schema, the description supplies the essential behavior, safety constraints, and response summary. It is complete enough for correct invocation, though explicit routing relative to set_custom_tags would have made it fully self-sufficient.

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 description clarifies that tag_ids accept numeric ids or labels, track_ids are the targets, ceiling acts as an upper bound, and expected_count gates writes. Since schema description coverage is 0%, this is meaningful compensation, though the precise object of the count/ceiling is slightly inferential.

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 action ('Add') on a specific resource ('tag_ids to track_ids') and distinguishes itself from set_custom_tags by emphasizing 'merge, never wipe.' An agent can clearly identify the tool's function and its non-destructive nature.

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 context for additive tagging ('merge, never wipe') and describes when validation will block the call, implying use when tags should be appended rather than replaced. It does not explicitly name alternative tools or list exclusions, but the intended usage is inferable.

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 full burden. It discloses that creating a smartlist involves rules with operators, and explains AND/OR semantics, but does not mention any mutation side effects, permission requirements, or error behaviors. This is a creation tool; lack of behavioral context for side effects is a gap.

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 a concrete example. The rule format example earns its place, but missing parameter details means a slightly fuller description could have been written concisely.

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 tool has an output schema and 4 params with 2 required. The description covers the tricky part (rules structure and AND/OR logic) but leaves 'name' and 'parent_id' unspecified. An agent could infer 'name' is required, but parent_id semantics are absent. This is incomplete for a create operation.

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%, so the description must explain all parameters. It only explains 'rules' format and match_all semantics; it omits 'name' and 'parent_id' semantics entirely. Even for rules, it leaves the full set of possible operators/enums undocumented.

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 ('create') and resource ('smartlist'), and provides the rule format example, which distinguishes it from sibling tools like delete_playlist or get_playlist_tracks. It does not explicitly warn about sibling overlap, but the purpose is clear enough.

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 explains match_all semantics and gives an example rule structure, which implies when the tool should be used (creating smartlists from rules). It does not state explicit alternatives or exclusions among siblings.

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 that this is a mutating operation, that it returns the tag with its new id, and that labels are unique library-wide (case-sensitive) — a genuinely useful failure-mode warning. However, it does not say what happens on a duplicate-label attempt or whether category_id must reference an existing category.

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 with zero waste. The primary action is front-loaded, and the second sentence delivers a high-value constraint (uniqueness + case-sensitivity) that an agent needs before calling. Both sentences earn their 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?

For a 2-parameter create tool with an output schema covering the return shape, the description is adequate but not full. It omits duplicate-handling behavior (especially salient given the uniqueness warning), whether the category must already exist, and any usage guidance relative to sibling tag tools.

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%, so the description must compensate. 'Inside a category' clarifies the role of category_id, and 'Tag labels are unique' implies label is the tag's name — meaning beyond the bare property titles. But neither parameter is explicitly defined, and format or validity constraints are left to inference.

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 (create) and resource (custom tag inside a category), and adds the return behavior (new id). This clearly distinguishes it from siblings like create_tag_category (creates a category), set_custom_tags / bulk_apply_tags (apply tags to tracks), and create_smartlist (a different entity).

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 uniqueness warning gives implicit guidance (ensure the label doesn't already exist before calling), and the phrasing implies this is for creating a tag rather than applying or listing tags. But there is no explicit when-to-use statement, no named alternatives, and no stated condition for choosing this over create_tag_category or set_custom_tags.

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 full responsibility for behavioral disclosure. It mentions the duplicate-rejection behavior and the return of the new id, which is useful. However, it does not disclose error handling, side effects beyond creation, or permission requirements, leaving a moderate gap.

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 deliver the purpose, an example, and the key constraint with no filler. The essential facts are front-loaded, making the description easy to parse quickly and entirely free of 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 two-parameter tool with an output schema, the description covers the core behavior, return value, and a critical constraint. The main omission is color, but it is optional, self-explanatory, and not required for correct calls. The output schema covers return structure, so completeness is high overall.

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%, so the description must compensate for parameter meaning. It partially covers 'label' by giving an example and stating uniqueness, but completely omits 'color'—its purpose, allowed values, or behavior. This is insufficient for a tool with an undocumented 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 action ('Create') and the resource ('custom-tag category') with an example, and distinguishes it from sibling tools like create_tag and list_custom_tag_categories. The return value is specified ('return it with its new id'). This leaves no ambiguity about the tool's function.

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 when to use the tool (when a new tag category is needed) but does not explicitly contrast it with alternatives or state exclusions. The uniqueness constraint hints at intended use but does not provide direct routing guidance relative to sibling tools.

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 present, but the description discloses key behaviors: return payload, folder cascade protection, the allow_playlist requirement, and irreversibility. This is strong transparency for a destructive 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?

Two sentences, front-loaded with the operation and result, then the essential conditions. 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?

For a 2-parameter destructive tool with an output schema, the description covers return value, type restrictions, flag semantics, and non-reversibility. There is no significant gap an agent would need filled.

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%, so the description must explain parameters. It gives real meaning to allow_playlist (needed to delete an ordinary playlist). playlist_id is only implied by 'Delete a smartlist', but the parameter name and required schema field make it unambiguous.

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 ('Delete') with the target resource ('a smartlist'), and immediately specifies the return shape. It distinguishes itself from sibling list/search/create tools by naming the deletion operation and the conditions around playlist types.

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 explicit conditions: folders are never deleted, and an ordinary playlist requires allow_playlist=True. Also warns there is no undo, so the agent knows when to apply and when to avoid. Since no sibling tool performs deletion, no alternative routing is needed.

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 behavioral disclosure burden. It explains the default compact field set, the effect of the fields parameter, the full=True behavior, and the approximate per-record size. This is meaningful behavioral context beyond the raw schema, though it does not cover pagination or error cases.

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?

Three sentences with no filler: the first states the core behavior and ordering, the second enumerates the default fields, and the third explains optional customizations. The most important information is front-loaded and 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?

The description covers the main call behavior, output shape, and payload-size trade-off, and an output schema exists to define return values. It could be more complete with pagination or behavior when both fields and full are supplied, but for a playlist-track retrieval tool it is largely sufficient.

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%, so the description must compensate for parameter documentation. It does this well for fields and full, listing the default fields and explaining what full=True adds. playlist_id is not described, but its meaning is clear from the name, schema title, and the tool's purpose.

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 and resource: 'Return a playlist's tracks in playlist order.' It clearly distinguishes the tool's scope from a single-track getter, though it does not explicitly name sibling alternatives. The resource and behavior are unambiguous.

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 gives clear context for when to use this tool: when you need the tracks belonging to a specific playlist. It does not explicitly provide exclusions or compare against siblings like get_track or search_tracks, but the purpose is clear enough for basic routing.

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 behavioral disclosure. It signals a read-only operation via 'Return' and specifies exactly what the record contains (metadata, tags, cues). It does not cover auth or error behavior, but for a simple retrieval these are not critical.

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, information-dense sentence. Every element earns its place: the operation, the resource scope, and the record contents are all stated without any 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 low complexity, one required parameter, and the presence of an output schema, the description is nearly complete. It does not need to explain the return structure because the schema handles that. The only minor gap is the lack of explicit sibling differentiation.

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%, so the description must compensate. It adds only the context that the record is 'for one track', which makes the role of track_id understandable but does not explain the ID format, where to obtain it, or any constraints beyond the schema's integer type.

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 ('Return') and a precise resource ('the full record for one track'), and enumerates the included components (metadata, tags, cues). This clearly distinguishes it from sibling list/search tools that operate over multiple tracks.

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 tool is for retrieving a single complete track record by track ID, which is clear usage context. It does not explicitly name alternatives or state when not to use it, but the scope is evident from the wording and sibling tool names.

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 behavioral burden. It explicitly discloses that it scans all tracks and is fast, and the word 'Summarise' implies a read-only operation. It does not belabor safety caveats, which is acceptable for a summary endpoint; the added performance/scope context goes beyond a mere tautology.

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 first sentence front-loads the tool's purpose and compresses the output list into a semicolon-separated enumeration without fluff. The second sentence adds a valuable performance clue. Every word earns its place, and the structure is easy for an agent to parse.

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 an output schema exists, the description need not spell out return structures. It provides the essential context for a zero-parameter tool: what it summarizes, the scope (whole library), and performance ('fast'). An agent can correctly select and invoke this tool with no missing information.

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 and the input schema is empty, so schema coverage is trivially 100%. The description cannot add parameter-level meaning beyond the schema, and per the zero-parameter baseline this is properly scored as 4.

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 'Summarise the whole library in one call' and then enumerates the exact aggregated outputs (track totals, bpm/key/energy counts, key notation, playlist counts, tag categories/tags). This is a specific verb+resource statement that clearly differentiates it from siblings like list_playlists or get_track, which target narrower slices.

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 gives clear context: this is the one-call whole-library summary, 'fast' and scanning all tracks. It implies the agent should use it when an overview of the entire library is needed rather than specific tracks/playlists, but it does not explicitly name alternative tools or state when-not-to-use, so it falls just short of 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?

With no annotations provided, the description carries the behavioral transparency burden. 'Return' and 'list' imply a non-mutating operation, which is useful, but the description does not disclose any other behavioral details such as ordering, pagination, or behavior with empty taxonomies. It is minimally adequate but not rich.

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 one concise sentence that is front-loaded with the action and resource. Every word adds value, and there is no redundant or boilerplate 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?

Given the tool has no parameters, an output schema is present, and the operation is a simple read-only listing, the description is complete enough for an agent to call it correctly. No additional context is necessary for successful invocation.

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 semantics because there is nothing to invoke; the empty schema already fully covers this aspect.

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 ('Return') and resource ('custom-tag taxonomy'), and clarifies the structure as categories with their tags. This clearly distinguishes it from sibling mutation tools like create_tag_category and create_tag, as well as from other list tools operating on different resources.

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 read-only listing intent is clear from the description, but it does not explicitly state when to prefer this tool over alternatives or mention related tools that could be used instead. For a zero-parameter read operation this is acceptable, yet the guidance remains implicit rather than explicit.

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, and it delivers: it discloses the row shape, ordering source, path-joining behavior, the effect of tree=True, and the absence of track counts. These are real behavioral traits beyond the schema fields.

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?

Three sentences, all information-dense and front-loaded. The flat list, row fields, and path semantics come first, followed by the parameter behavior and the sibling tool redirect. No filler or repetition.

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 tool is simple, has one optional parameter, and an output schema exists. The description covers return shape, ordering, path rendering, tree behavior, and what is intentionally omitted. Nothing essential is missing for correct invocation and interpretation.

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%, so the description must explain the sole parameter. It does: 'Pass tree=True for the raw nested tree' adds meaning beyond the boolean property name and default. It could have also noted the default behavior explicitly, but the default is 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?

Description opens with a specific verb ('Return every') and names the exact resources: playlists, folders, and smartlists. It also distinguishes the flat-list default from the nested tree mode, and points to get_playlist_tracks for contents, making it clear what this tool is and is not.

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 states when not to use this tool: 'No track counts either way; use get_playlist_tracks for contents.' It also explains the tree=True trade-off, which guides the agent on selecting the right call shape. This is strong usage routing relative to its siblings.

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 behavioral burden. It discloses that records are compact, that pagination is via limit/offset, and importantly guarantees that total_untagged is always the true count even when paged. This is valuable context beyond what the schema provides.

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, no filler. The core purpose is front-loaded, followed immediately by usage guidance and a key behavioral guarantee. Every clause 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?

The tool is simple with three optional parameters and an output schema. The description covers both invocation modes, pagination behavior, and the accuracy guarantee of total_untagged. Nothing critical is missing for an agent 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 description coverage is 0%, so the description must compensate. It explains playlist_id as a scope selector, and limit/offset as pagination controls, which is exactly the semantic meaning an agent needs. Defaults are left to the schema, which is acceptable.

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 action (List) and the specific resource (tracks with no custom tags), and notes the output format (compact records). While it doesn't explicitly contrast with sibling tools like get_playlist_tracks or search_tracks, the 'untagged' filter is a precise differentiator.

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 gives concrete usage direction: pass playlist_id to scope to one playlist, or omit it to scan the whole library and page with limit/offset. It explains the natural use case ('tagging drive') but doesn't explicitly address when to prefer sibling tools.

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 behavioral disclosure burden. It explains the return shape, the distinction between returned and total counts, the limit cap, and the rejection of unsafe filters — all useful non-obvious behaviors.

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: it states the action, gives a concrete filter example, then explains result semantics and a safety behavior. Every sentence earns its place without 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?

The description is adequate for a basic invocation using only the required filter parameter, and the output schema covers return structure. But the optional parameters remain under-specified, and there is no guidance about edge cases such as invalid fields or the exact shape of unsafe filters.

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%, so the description must compensate. It explains the filter format and limit behavior well, but leaves sort, fields, and source entirely to name inference, which is a significant gap for a tool with five 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 gives a clear action and resource: 'Search the library' with a filter mechanism over fields. It is specific enough to distinguish from tools like get_track, but it does not explicitly contrast itself with the sibling list/query tools.

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 intended use is implied: call this when you need tracks matching arbitrary field conditions. However, the description does not state when to prefer another tool, such as list_untagged_tracks or get_track, and offers no exclusionary 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?

With no annotations, the description carries full behavioral burden. It transparently discloses the destructive replacement behavior ('EXACTLY tag_ids (replace)'), the clear behavior ('Pass [] to clear'), and the accepted input forms for tags. This is sufficient and clearly communicated.

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: the core replace semantics appear first, followed by input format details, the clear case, and the alternative. Every sentence adds value with 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?

For a two-parameter mutation tool with an output schema and no annotations, the description covers the key behavioral aspects: exact replacement, clear semantics, accepted tag input forms, and guidance for additive use. Nothing critical is missing for an agent to 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 description coverage is 0%, so the description must compensate. It meaningfully explains tag_ids: it can contain tag ids or labels, gives concrete label examples, and states that an empty array clears tags. track_id is only implied by context, but the parameter name and description make it sufficiently clear.

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 verb ('Set'), the resource ('a track's custom tags'), and the exact semantics ('to EXACTLY tag_ids (replace)'). It also distinguishes itself from the sibling bulk_apply_tags by noting the alternative for many tracks.

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 explains when to use this tool: when you need exact replacement, when passing [] to clear, and how to add without disturbing existing tags. It names bulk_apply_tags as the alternative for many tracks, giving clear routing guidance.

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