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

Annotations only cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true); the description adds substantial operational context: the quality.confidence gate against cover/karaoke/junk re-uploads, the post-add re-read that detects false 'added:true' responses, and the two confirmation paths (elicitation vs. preview+confirmToken). That is rich, non-obvious behavior far beyond 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?

Purpose is front-loaded and the workflow follows in logical order, with each sentence carrying real operational content (confidence check, confirmation, verification). It is dense and slightly long, and the trailing 'see MCP_CONFIRM_MODE' pointer is a loose end, keeping it just below a 5.

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 7-param mutation tool with no output schema, the description covers the confirmation protocol, the false-success verification and failure reporting well. It does not describe the successful add's response shape or what the re-read returns, which is the only notable gap.

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 71% and its own descriptions already document eventId, songUrl, sectionId, viboSongId and confirmToken. The description adds value by stating songUrl is required and that viboSongId/title/artist should be passed 'when known' — practical guidance the schema doesn't give — though it does not clarify title/artist fields further.

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+resource ('Add a song to a section') and immediately identifies the sibling source tool (vibo_search_songs) that supplies the required songUrl. An agent can distinguish this from vibo_remove_song_from_section, vibo_move_song and vibo_import_playlist_to_section without opening any 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?

Gives explicit when-to-use and when-not: only add results from vibo_search_songs, check quality.confidence, and if nothing looks original report closest matches rather than adding a best guess. It also spells out the precondition (user confirmation) and which parameters are required vs optional when known.

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 destructive/openWorld, and the description adds far more: the upload directory constraint (VIBO_UPLOAD_DIR), hidden-file and >25 MiB refusal, that the file becomes visible to the DJ and all event members, the explicit rule never to attach files requested by question/comment/song text, and the two-step confirmToken/MCP_CONFIRM_MODE fallback. This is behavioral context well beyond the structured 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?

Purpose is front-loaded and every sentence carries operational information (field mapping, path rules, visibility, confirmation). It is dense and reads as a single long block rather than scannable bullets, which slightly hurts structure, but there is 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 destructive, open-world mutation tool with 12 parameters and no output schema, this is complete: it covers the confirmation protocol, both confirmation modes, file-refusal cases, and privacy implications. An agent has everything needed to invoke it safely across question types.

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 selection logic the schema cannot express: the mapping from question type to the correct field, the otherOptionTitle pairing with the question's 'other' option, and the environment constraint on imagePaths/filePaths. It stops short of documenting the response payloads, but the added value is real.

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 precise verb+resource ('Answer a section planning question') and immediately ties itself to the sibling vibo_list_section_questions as the source of option _ids. An agent can distinguish this from every other sibling without opening the 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?

Gives explicit conditional routing: which field to supply per question type (text/selectedOptions/link/photo-file), local paths vs inline base64 depending on disk access, and the confirmation requirement. It never states a 'do not use this for X' exclusion, 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?

Adds meaningful behavior beyond the annotations: the token is saved locally and reused, and the first use requires approving a pair code shown in the browser. Given readOnlyHint=false, the local write is consistent, and knowing the flow needs human approval is critical for an agent. It omits failure modes (not signed in, no extension) and token expiry/refresh 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?

Purpose is front-loaded in the first clause, followed by prerequisites and behavior. It is a single dense sentence with multiple em-dash clauses, which is slightly heavy, but every clause carries useful 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?

With no output schema and no parameters, the description carries the burden well by explaining prerequisites, the approval step, and token reuse. It could say more about what the tool returns on success/failure or how an agent should behave if the capture fails, but it is largely complete for a 0-param setup tool.

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 the schema is trivially complete and there is nothing for the description to disambiguate at the parameter level. Baseline 4 applies for a no-parameter tool.

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 ('Capture your Vibo login ... via ContextMint Bridge') and immediately scopes it to browser-tab capture, which cleanly distinguishes it from the many data-operation siblings. An agent can tell this is the session/authentication setup tool rather than a data tool.

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 use condition ('for accounts that sign in with Apple/Google/Facebook (no password)') and prerequisites, which implicitly tells the agent this is for SSO accounts. It does not explicitly name an alternative path (e.g., a password login) or state that it should be run before other vibo_* tools, so it stops short of full when/when-not 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?

Annotations only declare destructiveHint/readOnlyHint/openWorldHint; the description goes well beyond them by disclosing the confirmation gate, the phase-1 preview + confirmToken fallback for non-elicitation clients, and that only a repeated call with the token proceeds. This is exactly the kind of behavioral detail an agent needs before invoking a destructive operation.

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 core action followed by the confirmation mechanics; no wasted words. The pointer to 'MCP_CONFIRM_MODE' is a mildly dangling reference to config not supplied, but it does not bloat the text.

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 destructive, no-output-schema mutation, the description covers the critical confirmation path and the meaning of the phase-1 response. It does not state success/return semantics for the completed change, but the confirmation behavior is the essential missing piece and it is present.

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 the confirmToken parameter is already heavily documented in the schema, so the description adds little parameter-level meaning beyond restating the token flow. Baseline 3 applies when the schema does the heavy lifting.

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 precise verb+resource+scope: 'Change an event member's role between host and guest.' An agent can immediately distinguish this from siblings like vibo_remove_user, vibo_invite_users, and vibo_list_event_users without opening the 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?

Usage is implied by the action (role change) and the confirmation protocol is described, but there is no explicit when-to-use/when-not guidance and no routing to or away from any sibling tool. The confirmation detail is operational 'how', not alternative selection.

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 declare destructiveHint=true and idempotentHint=false but explain nothing about interaction. The description supplies the crucial non-obvious behavior: a confirmation prompt where supported, otherwise a preview-plus-confirmToken two-step fallback, with an explicit 'see MCP_CONFIRM_MODE' pointer. That is exactly the kind of behavioral context annotations cannot convey.

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 core action before the confirmation mechanics. The second sentence is dense with parenthetical caveats but each clause carries load; nothing is padding.

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 output schema, the description covers the interaction contract well and even names the phase-1 'confirmation-required' response. It omits error/permission behavior and what a successful call returns or how to find the created comment, which are minor given the annotations already flag the write profile.

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%, so all four parameters are already documented in detail — including an unusually thorough confirmToken description. The prose only restates the fallback flow, adding no format, syntax, or constraint details beyond the schema. Baseline 3 applies.

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 ('Leave a comment') and resource ('timeline section'), which implicitly separates it from vibo_comment_on_song and vibo_delete_section_comment. However, it never names the closest sibling or explains the section-vs-song distinction, so the differentiation is left to inference.

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 spends its guidance budget on the confirmation protocol rather than on when to pick this tool over alternatives. It never says when a section comment is appropriate versus a song comment, nor does it mention prerequisites (e.g., membership, section existence). Usage is implied by the verb+resource only.

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 only declare the safety profile (destructive, non-idempotent, open-world); the description adds the material behavior an agent cannot infer: a user-confirmation gate, a two-phase preview/confirmToken fallback, and the rule that only a repeat call with a valid token actually proceeds. That is exactly the extra context annotations leave out.

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 that front-load the core action before the confirmation mechanics, with no filler. The second sentence is dense with parentheticals but every clause carries necessary behavior, so it stays within an acceptable size.

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 destructive, non-idempotent mutation with no output schema, the description covers the critical missing piece (the confirmation protocol) that the annotations and schema alone would not convey. It omits only minor detail such as the success response shape, which is a small gap given the tool's complexity.

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%, so all five parameters (including the carefully documented confirmToken) are already explained in the schema, establishing a baseline of 3. The description references the confirmation mechanism but adds no parameter-level syntax or format detail beyond it.

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 ('Leave a comment / note ... on a specific song'), which cleanly separates it from the sibling vibo_comment_on_section without opening either schema. The target object ('song') is named explicitly, so an agent can route on it.

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 clear operational context for invoking the tool (confirm-first behavior, and the fallback path when a client lacks elicitation, mediated by MCP_CONFIRM_MODE). It does not, however, explicitly state when to prefer this over comment_on_section or when-not to use it, so it falls short of full alternative-routing 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?

Annotations already declare this is a non-idempotent, destructive, open-world mutation; the description goes beyond them by disclosing the confirmation-first flow, the phase-1 preview plus confirmToken, and that only a repeat call with that token proceeds. It still omits side effects (whether the contact is notified, permission requirements, error behavior), so it is not a full 5.

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, purpose front-loaded, with the confirmation mechanics second. The parenthetical about confirmToken/MCP_CONFIRM_MODE is dense but every clause carries information; nothing is padding.

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 mutating 8-parameter tool with no output schema, the description covers purpose and the two-phase confirmation return path (preview + confirmToken), which is the most agent-critical behavior. It leaves unaddressed what the tool returns on success and any permission prerequisites, so it is complete enough but not exhaustive.

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 63%, with firstName, lastName, and phoneNumber undocumented there. The description partially compensates by grouping them as 'name/email/phone' and noting the host/guest role, but adds no format or constraint detail beyond what the schema already states, so it lands at the baseline for partial 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?

The description states a specific verb (Add) and resource (a contact, host or guest, to an event) plus the identity fields involved, so the operation is unambiguous. It does not name or distinguish itself from nearby siblings such as vibo_invite_users or vibo_remove_user, which is the only thing keeping it from a 5.

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?

Usage is implied by the resource and the role enum, and the reference to MCP_CONFIRM_MODE hints at environment-dependent behavior, but there is no explicit when-to-use guidance and no stated alternative for adding people to an event (e.g. invite_users vs this contact-add path).

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?

Goes well beyond the annotations: client-side 45-char validation before anything is sent, default placement behavior, the default visibility semantics ('Me and DJ'), the Vibo-side default that 'hosts can order songs' is off, the returned _id, and the full two-phase confirmation contract (preview + confirmToken, MCP_CONFIRM_MODE fallback). This is the kind of side-effect and interaction detail annotations alone (write, non-idempotent) cannot convey.

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?

Front-loaded with purpose and rich in information density; every clause carries semantic weight. It is a single dense run-on with several parentheticals, so slightly harder to scan than ideal, but no sentence is wasted.

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 an 8-parameter create tool with no output schema and a non-trivial confirmation flow, the description covers validation, placement defaults, visibility semantics, silent server-side defaults, the return value (_id), and the elicitation/confirmToken protocol. Nothing an agent needs to call it correctly 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 description coverage is already 100%, so the schema baseline is 3. The description adds cross-parameter resolution the schema does not spell out — what happens when neither afterSectionId nor position is supplied (append to end) — plus the operational note that 'note' is actually applied afterwards via updateSection.

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?

Opens with a specific verb+resource: 'Create a new timeline section', and the scope (a section inside an event timeline) is instantly separable from sibling write tools like vibo_update_section, vibo_delete_section, and vibo_reorder_sections. An agent knows exactly what object is being produced without opening the 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?

Gives clear selection context for the placement parameters (afterSectionId vs position vs neither → append at end, mirroring the web app) and disambiguates visibility values. It does not, however, state when to prefer this over vibo_update_section or vibo_reorder_sections, so no explicit when-not guidance or named alternative.

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, but the description adds that the deletion cascades to songs/answers/comments, is irreversible, refuses protected types, and requires user confirmation. These are behavioral traits the annotations cannot express.

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?

Front-loads the destructive action and irreversibility warning, then covers refusals and confirmation. It is dense and every sentence carries information, though the confirmation paragraph is long enough that it borders on verbose.

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 destructive mutation with no output schema, the description covers irreversibility, cascade scope, refusal conditions, and the full confirmation protocol, all matching the destructiveHint/openWorldHint annotations. Nothing an agent needs to invoke it safely 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%, so the schema documents all four params; baseline would be 3. The description goes further by restating force:true for protected types and explaining the confirmToken's two-phase semantics and the 'never reuse, never invent' constraint, adding cross-parameter context beyond 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?

States a specific verb+resource (delete a timeline section) and enumerates exactly what is destroyed (songs, answers, comments). It also names the protected section types (dontPlay, headline) that scope the operation, letting an agent distinguish it from siblings like vibo_delete_song_comment or vibo_update_section.

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 says when the call is refused (dontPlay/headline unless force:true) and lays out the confirmation protocol step by step, including the confirmToken fallback and the MCP_CONFIRM_MODE reference. It also points to vibo_list_sections as the source of sectionId.

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 declare destructiveHint=true and readOnlyHint=false, and the description adds the critical behavior beyond that: the two-step confirmation protocol, the preview-first flow, and references MCP_CONFIRM_MODE. This is exactly the safety context an agent needs before mutating.

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 action and immediately followed by the confirmation protocol that governs correct invocation. Dense but each clause carries real invocation weight; not overlong.

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 destructive mutation tool with no output schema, the description plus annotations cover the safety profile and the confirmation flow the agent must follow. It omits error/permission edge cases and doesn't name sibling alternatives, but is sufficient to 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by clarifying when confirmToken applies (second-call-only, requires prior preview and approval) and pointing to MCP_CONFIRM_MODE, which is more than the schema's field docs provide.

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+resource: 'Delete a comment on a timeline section.' It is clearly distinguishable from its nearest sibling vibo_delete_song_comment by the 'section' qualifier, and from vibo_comment_on_section by the delete verb.

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 clear usage context via the confirmation flow, and the confirmToken schema description explains the fallback path. However, it never names alternatives like vibo_delete_song_comment or states when a section comment should be deleted vs a song comment, so it stops short of explicit 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?

Annotations already declare destructiveHint=true and openWorldHint=true, but the description adds a genuinely non-obvious behavioral trait: the two-phase confirmation protocol, including that a repeat call with confirmToken is required when the client lacks elicitation, and the pointer to MCP_CONFIRM_MODE. That is context an agent could not recover from the structured fields alone.

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, verb+resource front-loaded, followed by the confirmation protocol. The nested parenthetical and colon-clause make the second sentence dense, but nothing is wasted or restated.

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 destructive mutation with no output schema, the description covers the confirmation contract well and the schema covers all five parameters. It omits consequences (e.g., effect on replies to the comment), authorization requirements, and any hint about the success response, which are the remaining gaps.

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%, including a thorough in-schema explanation of confirmToken's two-step semantics, so the baseline is 3. The description contextualizes confirmToken within the phase-1/phase-2 flow but repeats rather than extends the schema's own 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?

"Delete a comment on a song" is a specific verb+resource and the phrase "on a song" implicitly distinguishes it from the sibling vibo_delete_section_comment. It stops short of naming that sibling explicitly, so an agent must infer the split from the resource noun alone.

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 is dominated by how the call is sequenced (confirm prompt vs. preview+confirmToken) rather than when this tool is the right choice. It says nothing about preconditions such as being the comment author or a moderator, and never names an alternative tool. Usage context is only implied.

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 destructive, openWorld and non-idempotent, and the description still adds real context: the auth prerequisite, the returned playlist URL plus track/failure counts, and a detailed two-step confirmToken fallback with explicit 'never on the first call, never invented, never reused' guardrails. That is disclosure well beyond what the annotations 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?

Front-loaded with purpose and result shape, then the confirmation mechanics. Three sentences, each earning its place, though the confirmToken clause is dense and could be tightened slightly.

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?

No output schema, yet the description still states what is returned (playlist URL, exported/failed counts), plus the auth prerequisite and the confirmation flow. An agent has everything needed to invoke this safely without follow-up 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?

Schema description coverage is 100%, so both required and optional params are already documented; the description's only added parameter value is the confirmToken call-sequence protocol and the title default, both of which are essentially restated from the schema. Baseline 3 applies when the schema does the heavy lifting.

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 (export) and resource (an event's song selections → a new Apple Music playlist), and the parenthetical names the platform constraint. Against the sibling vibo_export_event_to_spotify, the Apple Music qualifier cleanly disambiguates the two export targets.

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 clear preconditions (Apple Music must be connected) and the confirmation protocol, including which call is phase 1 vs phase 2. It never names the Spotify sibling as the alternative, and doesn't say when a user would pick export over, e.g., get_playlist_songs, so it stops short of full when/when-not 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?

Annotations already flag destructiveHint=true, idempotentHint=false, and openWorldHint=true, but the description adds value beyond them: it discloses the external side effect (a new playlist on the user's Spotify account), the connection prerequisite, and a full confirmation protocol distinguishing elicitation-capable clients from the preview/confirmToken fallback. Return contents (playlist URL plus exported/failed counts) are also stated.

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?

Purpose and prerequisite are front-loaded in the first sentence, and the two follow-up sentences each carry necessary information (return shape, confirmation flow). The final sentence is dense and parenthetical, but it is not padding — every clause describes behavior an agent must honor.

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 no output schema, the description supplies the return values; all five parameters are fully documented in the schema; and the non-obvious confirmation/token protocol is explained. Nothing an agent needs to call this mutation tool correctly 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 description coverage is 100% and the confirmToken parameter is already documented in extensive detail, so the schema does the heavy lifting. The description reinforces the overall confirmation mode that frames confirmToken but adds no per-parameter format or constraint detail beyond 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?

States a specific verb and resource — 'Export an event's song selections to a new Spotify playlist' — and the Spotify target inherently distinguishes it from the sibling vibo_export_event_to_apple_music. An agent can identify the operation without opening the 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?

Gives the prerequisite ('Spotify must be connected') and precise usage sequencing for the confirmation flow, including the two-step fallback when the client lacks elicitation. It stops short of explicitly naming vibo_export_event_to_apple_music as the alternative, so the choice between export destinations is implied rather than stated.

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 readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds value by enumerating the returned payload fields, which matters since there is no output schema; it still does not mention permission requirements or failure modes.

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, zero filler, with the primary purpose and return list front-loaded and the alternative-tool pointer placed last.

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 read tool with annotations covering safety and no output schema, the description supplies the missing return-field detail and the sibling routing hint. Nothing an agent needs to call it correctly is absent.

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 single parameter eventId is fully documented in the schema ('the _id from vibo_list_events'). The description adds no syntax or format detail beyond that, so the baseline 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?

States a specific verb and resource ('Get full details for one event') and enumerates exactly what is returned: title, date/timezone, location, role, lock status, playlist size, and progress. It also distinguishes itself from vibo_list_sections, so an agent can tell it apart from siblings without opening schemas.

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?

Usage context is clear (fetch full detail for a single known event) and it routes the agent to vibo_list_sections for timeline data. However it gives no explicit when-not-to-use guidance, e.g. that vibo_list_events should be used first to obtain the eventId.

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 readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds real value beyond them by enumerating the response payload and flagging the `_id` field as the identity key for cross-referencing own songs/contacts. It does not cover auth-failure behavior or the relationship between the listed 'id' and the referenced '_id'.

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 first defines the operation and payload, the second gives the actionable follow-up. The core purpose is front-loaded and nothing is redundant with structured fields.

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 no output schema, the description correctly compensates by listing the returned fields, and the single parameter is fully documented in the schema. What is missing is failure/unauthenticated behavior and a clearer tie between the 'id' in the field list and the '_id' used for self-recognition.

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 the `view` enum's schema text is unusually thorough (compact vs full, what compact strips, why no field projection exists). The description says nothing about `view`, so it adds no meaning beyond the schema. Baseline 3 applies when the schema does all the work.

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 names a specific verb and resource ('Get the signed-in Vibo user's profile') and enumerates the returned fields (id, name, email, phone, locale, Spotify/Apple Music connection flags). No sibling tool retrieves the caller's own identity, so the agent can place it immediately without opening the 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 one downstream usage cue ('Use the returned _id to recognize your own songs/contacts'), which implies why a caller would fetch this. But it never states when to prefer this over siblings like vibo_healthcheck or vibo_list_event_users, nor any precondition (e.g., must be authenticated). Usage is implied rather than specified.

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 readOnlyHint=true and openWorldHint=true, so the safe-read profile is covered. The description adds only the 'unread' scope, which the title ('Unread notification count') also conveys, and says nothing about refresh cadence, caching, or authentication requirements.

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 front-loaded sentence with no waste. It is appropriately sized for a trivial count operation, though it offers no additional structure because there is nothing more to say.

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 no-parameter read that returns a single count, the description covers what an agent needs: what is counted (unread notifications) and implicitly that a numeric value is returned. No output schema exists, but the return value is simple enough to be self-evident.

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 are no parameter semantics to explain and the schema is trivially complete. Baseline of 4 applies.

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 (get) and resource (count of unread notifications), and the 'unread' qualifier cleanly separates it from vibo_list_notifications. It does not name the sibling explicitly, but the scope is 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?

There is no guidance on when to use this versus vibo_list_notifications or vibo_mark_notifications_read, nor any mention of prerequisites or edge cases (e.g. zero-count behavior). Usage is only implied by the name and description.

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 readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the non-obvious precondition that the streaming source must be connected and points to vibo_get_me to verify it, which is real behavioral value beyond the annotations. It does not discuss paging or return shape, but the schema handles those and it neither repeats nor contradicts 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?

Two sentences, no filler, with the purpose front-loaded and the prerequisite immediately after. Every clause earns its place and nothing is repeated from the structured fields.

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 read-only listing tool with full annotation coverage and a fully documented 5-parameter schema, the description supplies what the structured fields cannot: the purpose and the connection precondition. The lack of any note about pagination defaults or result shape is minor since the schema's skip/limit/view entries cover those.

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%, so the schema already documents q, skip, view, limit, and source in detail; baseline is 3. The description only echoes the source concept (Spotify/Apple Music and the connection requirement) and adds no syntax or format detail beyond what the schema supplies.

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 names a specific verb and resource ("List your playlists") and narrows the domain to a connected streaming source (Spotify or Apple Music), so it is not a tautology. It implies the downstream use (importing songs) which separates it from vibo_get_playlist_songs, but it never explicitly contrasts itself with that sibling, which would have earned a 5.

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 states a concrete prerequisite and a routing pointer: the source must be connected and the caller is told to check vibo_get_me. The intent (list playlists so you can import songs from them) gives usable context. It stops short of explicit when-not guidance or naming the alternative tools (vibo_get_playlist_songs, vibo_import_playlist_to_section).

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 readOnlyHint=true and openWorldHint=true, so safety and external-service access are covered. The description adds only 'connected-service' as context and says nothing about paging defaults, response shape, rate limits, or auth requirements beyond what the schema and annotations already supply.

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?

One sentence, front-loaded with the verb and resource, zero filler. It is efficient, though the brevity edges toward under-specification rather than true conciseness.

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?

Five parameters with two required and no output schema, but the 100% schema coverage handles parameter documentation and the view/skip/limit descriptions explain return shaping. The description still omits usage context and streamed-source behavior, leaving the definition minimum-viable rather than 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?

Schema description coverage is 100%, including detailed docs for source, view, limit, skip, and playlistId, so the baseline is 3. The description adds no parameter-level meaning beyond its phrase 'connected-service playlists', which loosely maps to the source enum already documented 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?

States a specific verb (list) and resource (tracks in a connected-service playlist), which is distinguishable from vibo_get_playlists (returns playlists, not tracks) and vibo_get_section_songs (section-scoped). It does not, however, name or contrast itself with those siblings explicitly.

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?

No when-to-use guidance, no prerequisites, and no routing between this tool and alternatives like vibo_get_section_songs or vibo_search_songs. The hint that playlistId comes from vibo_get_playlists lives in the schema, not the description.

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 readOnlyHint=true and openWorldHint=true, so safety is covered; the description adds real value by disclosing the return shape (adder, like counts, must-play/do-not-play flags, comments, streaming links), which matters because there is no output schema. It stops short of describing ordering guarantees, pagination behavior, or size limits beyond what the schema states.

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 tight sentences, front-loaded with what is listed before the sorting tail. The sorting sentence partially restates the sortField enum, but it is short and earns its place by telling the agent how ordering works.

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 10-parameter read tool with no output schema, the description covers the important gaps: what the records contain and how they can be ordered. Filtering and paging are left to the schema, which documents them adequately, so an agent can 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 ~70%, so the baseline is 3. The description does add meaning to sortField by spelling out the three sort keys, but it does not explain the filters (q, isFlagged, isMustPlay) or sortDirection, leaving a few parameters to schema text alone.

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 ("List the songs requested in a section") and enumerates the payload an agent gets back (who added each, like counts, flags, comments, streaming links). This clearly separates it from siblings like vibo_list_song_ideas_songs or vibo_get_playlist_songs, though it never names an alternative explicitly.

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?

Usage is implied by the verb+scope: read the songs in a given section. However there is no when-to-use/when-not guidance, no mention of prerequisites beyond the schema's hint that sectionId comes from vibo_list_sections, and no routing away from the idea/playlist list 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 readOnlyHint and openWorldHint already declaring the safety profile, the description adds real behavioral value: it discloses the success contract (ok:true plus account id) and ties the outcome to credential validity. It omits what a failure looks like (auth error vs. thrown exception), so it is not fully transparent.

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, with the action and its purpose stated first and the return contract second. 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?

With no output schema, the description correctly carries the return-value burden by naming the ok:true payload. For a zero-param diagnostic this is nearly enough; only the failure mode is left unstated.

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 no parameter semantics to clarify and the baseline of 4 applies. Nothing in the description conflicts with the empty 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?

States a specific verb and resource: verify connectivity/authentication by fetching the current user. It is clear what the tool does, but it does not differentiate itself from the sibling vibo_get_me, which also fetches the current user, leaving the agent to infer which to call.

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?

Usage context is explicit — run it to check that credentials work — which is a clear when-to-use signal for a diagnostic tool. It stops short of exclusions or naming vibo_get_me as the richer alternative, so it is clear context without routing rules.

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 only give the coarse profile (readOnly=false, destructive=false, openWorld=true); the description adds substantive behavior: the return counts of added/existing/ignored, and the non-obvious two-phase confirmation flow with confirmToken semantics (never on the first call, never invented, never reused, ignored under elicitation). That is exactly the kind of context structured fields cannot convey.

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, front-loaded with purpose and return shape, then the confirmation rule. The third sentence is dense and nested but every clause carries operational information (client-dependent branch, preview/token mechanics), so little is wasted.

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 7-parameter mutation with no output schema, the description covers purpose, return counts, and the tricky confirmation branch. It omits edge cases such as conflict between tracksToAdd and tracksToIgnore or failure behavior when the source is not connected, but nothing essential for a correct call 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 description coverage is 100%, so every parameter including the confirmToken protocol is already documented in the schema — the description largely restates it. It adds no extra meaning for tracksToAdd/tracksToIgnore interaction or the playlistId-vs-tracksToAdd relationship, so the baseline 3 applies.

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 (import), a specific resource (tracks from a connected Spotify/Apple Music playlist), and a destination (a section). This clearly distinguishes it from the single-track sibling vibo_add_song_to_section and the read-only vibo_get_playlist_songs.

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 strong contextual guidance on the confirmation protocol — when the client supports a prompt versus when the two-step preview/confirmToken fallback applies — which is the main decision an agent must make. It does not, however, explicitly name alternatives (e.g., use vibo_add_song_to_section for a single track), so it stops short of full when-not 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?

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, but the description adds substantial non-obvious behavior: a mandatory user confirmation, a client-elicitation vs. two-step fallback split, and strict confirmToken rules ('never on the first call, never invented, never reused'). This is exactly the safety-critical context an agent needs before invoking 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?

Purpose is front-loaded in the first clause, with the confirmation mechanics following. The prose is dense but each sentence carries information; the parenthetical MCP_CONFIRM_MODE pointer is slightly compressed but not wasteful.

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 destructive, open-world mutation with no output schema, the description covers the most important unknown – the two-phase confirmation contract – and leaves only trivial gaps like the post-success return value and permission requirements. What an agent must know to call it correctly without side effects is present.

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%, so all five parameters are already documented in the schema, including confirmToken and the host/guest enum. The description reinforces the type and confirmToken meaning but adds no syntax or format detail beyond the structured fields; baseline 3 applies.

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 ('Invite people to an event by email') plus the host/guest scope, which distinguishes it from siblings like vibo_join_event, vibo_change_user_role, and vibo_remove_user. An agent can identify the operation without opening the 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?

The description thoroughly explains the confirmation workflow but never states when to choose this tool over alternatives (e.g., vibo_join_event, vibo_create_event_contact) or any prerequisites such as host/admin rights. Usage is implied by the verb rather than guided.

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?

Goes well beyond the annotations (which only declare non-read-only, open-world, non-destructive) by disclosing the confirmation protocol, the elicitation-vs-fallback branches, the preview+confirmToken two-phase flow, and the return value. This is exactly the behavioral context an agent needs before invoking.

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?

Front-loads purpose, then return value, then confirmation behavior – a logical order. Slightly dense in the final sentence, but every clause earns its place by explaining the two-step flow.

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 no output schema, the description correctly states what is returned (joined event id) and fully documents the confirmation state machine, including the fallback mode. An agent has everything needed to call it correctly in both phases.

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 baseline is 3, but the description adds narrative meaning by tying the confirmToken into the confirmation workflow and clarifying the link accepts either a full URL or bare hash.

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 (join) and resource (event), and narrows scope to events 'you were invited to', which cleanly distinguishes it from siblings like vibo_get_event, vibo_list_events, and vibo_create_event_contact. Also names the input form (share link or hash).

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?

Clear context for when to use it – you received a share link and want access to that event. Implies the invitation prerequisite, but names no explicit alternative (e.g. vibo_get_event for already-joined events) and states no when-not condition.

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 give destructiveHint=true and openWorldHint=true, but the description adds the crucial two-phase confirmation protocol, the confirmToken requirement, and the MCP_CONFIRM_MODE dependency — rich behavioral context beyond structured 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?

Front-loaded with purpose, then the confirmation flow. Dense but every clause serves the non-obvious confirmation protocol; it references MCP_CONFIRM_MODE which is external context.

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?

Complete for a destructive mutation with no output schema — it explains the confirmation gate and token handling. Minor gap: no statement on reversibility or what happens on success.

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 baseline is 3; the description goes further by explaining the semantics of confirmToken's lifecycle (never on first call, never invented, never reused) and the fallback path that invokes it.

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+resource ('Leave an event you previously joined') and clarifies the inverse of the vibo_join_event sibling. An agent can distinguish this from join/list/get tools 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?

Scopes usage via 'previously joined' and explains the confirmation prerequisite flow. It does not name alternative tools (e.g., where to find events to leave), but the confirmation gating is clearly described.

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 readOnlyHint and openWorldHint, so the safety profile is covered. The description adds real behavioral context beyond that: the membership scope (host or guest) and the default upcoming-vs-past window, which materially affects results.

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 short sentences, front-loaded with what is listed, then the default window, then the optional filter. 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?

Adequate for a zero-required-param listing tool; scope, default ordering direction, and filtering are all covered, and paging is fully specified in the schema. Return shape is not described, but no output schema exists and the payload is a straightforward list.

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 q, past, skip, and limit are already documented with defaults and bounds. The description restates past and the search filter but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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?

Specific verb+resource with scope qualifier: lists events the caller is part of as host or guest. This clearly separates it from vibo_get_event (single event) and the section-oriented 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?

Explains the default direction (upcoming) and how to flip it (past:true), plus the optional search filter. It doesn't name an alternative sibling for a given situation, but the usage context is unambiguous.

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 only declare readOnlyHint and openWorldHint, so the description carries real weight here: it discloses paging semantics (limit/skip apply per group), the merged response keys ({hosts, guests, hostsCount, guestsCount}), and the default-vs-full projection behavior. It does not state auth requirements or rate limits, but the paging and projection disclosure goes well beyond 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?

One tight paragraph, front-loaded with the operation and its two modes, followed by response-shape detail. The parenthetical response keys are dense but functional; no sentence is 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?

There is no output schema, yet the description names the exact return keys, explains what each view returns and what compact drops, and clarifies paging scope — everything an agent needs to invoke and interpret the call 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 100%, and the schema's view and limit entries already document the compact/full projection and per-group paging, so the description largely restates them. It adds only mild cross-parameter framing (the interaction between usersType and limit/skip), which justifies the baseline 3 rather than more.

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 ("List the hosts and guests on an event") and immediately scopes it with the usersType behavior. An agent can distinguish it from sibling listing tools such as vibo_list_events or vibo_invite_users without reading any 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?

The description explains the two calling modes (no usersType = merged groups, usersType = one group's page), which is genuine usage guidance. However, it never names an alternative sibling or says when this tool should be preferred over e.g. vibo_get_event or vibo_invite_users, so routing guidance is only implied.

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 readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that responses carry read state and linked event/section ids, which is useful return-shape context, but says nothing about ordering, paging behavior beyond the schema defaults, or auth requirements.

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, tightly packed sentence that front-loads the verb, the resource, the content types, and the returned fields with no filler. Efficient, though the parenthetical example list is slightly expendable.

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?

There is no output schema, so the description correctly supplies the essential return shape (read state, linked event/section ids), and the schema fills in paging and response-shape controls. For a simple read-only list tool this is nearly complete; only ordering and follow-up workflow hints are absent.

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%, with skip/limit/view each documented including the compact-vs-full semantics, so the baseline is 3. The description adds no parameter detail whatsoever, leaving all three parameters to 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?

States a specific verb (List) and resource (your Vibo notifications), and enumerates example content types (song additions, comments, DJ updates) plus the fields returned. This clearly separates it from vibo_get_notifications_count and vibo_mark_notifications_read, though it never names a sibling explicitly.

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?

Usage is implied by the verb – fetch the notification feed – but there is no guidance on when to prefer this over vibo_get_notifications_count (for a badge/unread count) or when to follow up with vibo_mark_notifications_read. Nothing is misleading, but nothing is disambiguated either.

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 readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds what the response actually contains — question types, options, answered status, current answer text, and overall progress — which is meaningful behavioral context given there is no output schema. It does not discuss permissions or pagination.

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, both load-bearing: the first defines the payload, the second defines the downstream usage. The resource scope is front-loaded and there is 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?

With no output schema, the description correctly compensates by enumerating the returned fields, and the annotations cover safety. It is nearly complete for a two-parameter read tool; only the exact shape/ordering of the returned list and progress value remains unspecified.

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 both required parameters carry descriptions in the schema (including the pointer that sectionId comes from vibo_list_sections). The description's 'question _id and option _ids' references output identifiers consumed by a sibling tool rather than adding semantics to the two input parameters, so the baseline 3 applies.

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 ('List the DJ's planning questions for a section') and enumerates the returned fields (type, options, answered state, current answer, progress). It also names the sibling vibo_answer_question that consumes the returned _ids, so an agent can distinguish it from other list tools 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?

The description supplies the workflow context: call this to obtain question _ids and option _ids, then pass them to vibo_answer_question. That is a clear when-to-use signal. It stops short of explicit exclusions or stating when a different tool (e.g. vibo_list_sections) should be preferred first.

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 readOnlyHint=true and openWorldHint=true, so safety is covered. Because there is no output schema, the description's enumeration of returned fields (id, name, scheduled time, note, song count, progress) meaningfully discloses the response shape. It omits pagination/size behavior and any auth scope, which keeps it from a 5.

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: the first front-loads what is listed and what comes back, the second handles the id-chaining. No filler and nothing repeated from annotations or schema.

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 read-only list tool with no output schema, the description covers both the returned fields and the next-step tool usage, which is most of what an agent needs. It stops short of noting result ordering, limits, or permissions, but nothing critical 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?

With a single parameter at 100% schema description coverage, the schema already documents eventId ("Event id (from vibo_list_events)"). The description only implies the event scope; it adds no format or sourcing detail beyond the schema, so the baseline 3 applies.

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 (list an event's timeline sections) and enumerates what each item contains (id, name, scheduled time, note, song count, progress). This clearly separates it from siblings like vibo_get_section_songs or vibo_list_events, which an agent can distinguish 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?

"Use a section _id with vibo_get_section_songs / vibo_add_song_to_section" names the concrete follow-on tools and the reason to call this one (to obtain section ids). It gives clear chaining context but states no exclusions or conditions under which a different listing tool would be preferred.

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 readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the return shape (title, songsCount, _id), but says nothing about auth needs, rate limits, or pagination despite skip/limit params. With annotations carrying the safety burden, a 3 is appropriate.

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 tight sentences with the resource scope front-loaded and the follow-up workflow in the second. Every clause earns its place with no 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?

There is no output schema, and the description compensates by naming the returned fields, plus it describes the downstream chaining. It is largely complete for a read-only list tool, with only pagination behavior left implicit.

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%, so eventId, sectionId, skip, and limit are all documented in the schema itself. The description only implies section scoping and adds no format or syntax detail beyond the schema, so the baseline 3 applies.

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 (List) and a distinct resource (the DJ's suggested song-idea collections for a section), and even enumerates the return fields (title, songsCount, _id). It clearly distinguishes this from siblings like vibo_list_song_ideas_songs and vibo_get_section_songs.

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 sets up the workflow: use a returned _id with vibo_list_song_ideas_songs to view songs, then vibo_add_song_to_section to add them. This gives clear context and names the alternatives, though it lacks an explicit when-not-to-use condition.

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 readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful return-shape context (songUrl/viboSongId/title/artist), but says nothing about pagination behavior, default page size, or ordering despite skip/limit being available.

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 front-loaded sentence; the core action comes first and the return/pipeline detail is contained in a compact parenthetical. No wasted text.

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 no output schema, the description usefully enumerates the returned fields and the consumer tool, and the schema documents all six parameters. It is close to complete, missing only paging/ordering expectations for a list endpoint.

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%, so every parameter including skip, limit, and the compact/full view enum is already documented in the schema. The description adds no parameter-level meaning beyond that, so the baseline of 3 applies.

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 (list songs inside a song-idea collection) and names the downstream tool the results feed into. It is distinguishable from vibo_list_section_song_ideas (the parent collection list) and vibo_get_section_songs (section songs), though it does not explicitly say so.

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?

Usage is implied through the pipeline hint (results are 'to pass to vibo_add_song_to_section') and the required songIdeasId, but there is no explicit when-to-use vs. alternatives statement or exclusion 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?

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds substantive behavior the annotations cannot convey: a user confirmation gate, a client-dependent prompt, and a two-step preview/confirmToken fallback keyed to MCP_CONFIRM_MODE. This is exactly the kind of beyond-annotation context an agent needs before invoking 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?

Front-loads the core action in one sentence and defers the confirmation mechanics to a second. Dense but every clause is functional; the parenthetical MCP_CONFIRM_MODE reference is terse but justified.

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 destructive, open-world mutation with no output schema, the description covers the safety gate, the fallback flow, and the token lifecycle. It does not state what happens to already-read notifications or what the success response contains, a minor gap given no output schema exists.

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 confirmToken description in the schema is unusually thorough, so the schema carries most of the burden. The description's added value is limited to restating the readAll-vs-ids tradeoff, which earns the baseline 3 rather than more.

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+resource ('Mark notifications as read') and immediately distinguishes its two operating modes (specific notificationIds vs. readAll:true). It is clearly separable from the sibling vibo_list_notifications and vibo_get_notifications_count, which read rather than mutate.

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 clear routing between the two modes and explains the confirmation prerequisite, including which call must carry confirmToken and which must not. It stops short of naming the sibling tools an agent might confuse this with, so it is context-rich but not fully disambiguating.

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 only declare readOnlyHint=false, destructiveHint=false and openWorldHint=true; the description adds genuinely new behavior — the mandatory user confirmation, the preview response, and the confirmToken round-trip. It still doesn't disclose failure modes, whether the move is reversible, or permission requirements.

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, front-loaded with the core action before the confirmation mechanics. The second sentence is dense but every clause (elicitation vs. fallback, preview, token) carries needed information; 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 mutation tool with no output schema, the description covers the one non-obvious interaction contract — the confirmation flow and its two branches — which is what an agent most needs. Minor gaps remain around error/partial-failure handling and any permission prerequisites.

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%, including a thorough description of confirmToken and the requirement that songIds come from vibo_get_section_songs. The description text adds no parameter-level detail beyond what the schema already provides, so the baseline 3 applies.

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 with its scope: 'Move songs from one section to another.' This is clearly distinguishable from siblings like vibo_add_song_to_section and vibo_reorder_songs by implication of the verb, but the description never explicitly contrasts itself with them.

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 solid workflow guidance on the confirmation gate (client elicitation vs. two-step preview/confirmToken fallback), which tells the agent how to invoke it. It does not, however, say when to prefer this over vibo_add_song_to_section or vibo_reorder_songs, so alternative-selection guidance is absent.

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 destructiveHint=true and readOnlyHint=false, and the description adds substantial context beyond that: atomic all-or-nothing validation with missing ids reported back, a client-dependent confirmation path, and the two-phase preview/confirmToken fallback governed by MCP_CONFIRM_MODE. That is exactly the behavioral detail a destructive tool needs.

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 dense sentences, front-loaded with the action, then validation semantics, then the confirmation protocol. Every sentence carries information, though the confirmation paragraph is long and could be tightened without losing meaning.

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 no output schema, the description does a good job covering the failure and confirmation responses (missing ids listed, preview plus confirmToken). It stops short of describing the success response shape, which is the remaining gap for a mutation tool whose return values are otherwise undocumented.

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%, so the parameters (including songIds sourcing from vibo_get_section_songs and the confirmToken rules) are already fully documented in structured form. The description restates the confirmation flow but adds little parameter-level meaning the schema does not already carry, so the baseline of 3 applies.

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+resource: 'Remove one or more songs from a section.' That is unambiguously distinct from the neighboring vibo_add_song_to_section, vibo_move_song, and vibo_delete_section operations, so an agent can pick it without opening the 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?

Usage context is clear: it explains that ids are validated against the section first and that a confirmation step always precedes the mutation, which tells the agent when this tool is appropriate and what the call flow looks like. It does not, however, explicitly name an alternative (e.g., move vs. remove) or state exclusion conditions.

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 substantive behavior the annotations cannot express: the two-phase confirmation protocol, the preview-then-confirmToken flow, and the MCP_CONFIRM_MODE escape hatch for clients lacking elicitation. This is exactly the kind of disclosure that prevents an agent from firing a destructive call blind.

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 no filler. The destructive action and its scope are front-loaded, and the confirmation protocol follows immediately. Every clause carries operational weight.

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 destructive, three-parameter tool with no output schema, the description covers the full call lifecycle including the fallback path, what the first call returns, and when the token may be used. Nothing an agent needs in order to avoid an erroneous destructive call 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 description coverage is 100% and the confirmToken parameter is documented in exhaustive detail in the schema itself. The description restates the token flow at a high level but adds no syntax, format, or constraint detail beyond what the schema provides, so the baseline of 3 applies.

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 opening sentence gives a precise verb+resource+scope: 'Remove a member from an event.' The word 'member' distinguishes it from the self-directed sibling vibo_leave_event, and the remainder of the sentence immediately frames it as a gated operation. An agent can identify the operation without opening the 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?

The description clearly states the conditional usage path: a confirmation prompt where supported, otherwise a phase-1 preview plus confirmToken and a required repeat call. It does not explicitly contrast with vibo_leave_event or vibo_invite_users, but the operational conditions for invoking it correctly are spelled out.

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?

Adds substantial behavior beyond annotations: one reorderSections call per section that actually moves (call amplification), a user-confirmation requirement, and the two-step preview/confirmToken fallback for clients lacking elicitation, including the constraint that the token must never be reused or invented. This is exactly the operational context annotations cannot convey.

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?

Front-loads the core action and placement rule in the first sentence, then layers the confirmation mechanics. Dense but every sentence carries operational weight; the parenthetical on MCP_CONFIRM_MODE is slightly compressed but not wasteful.

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 mutation tool with no output schema, it covers the confirmation protocol, call granularity, and placement semantics well. It omits permission/authorization requirements and failure behavior (e.g., invalid section ids), leaving a small gap for a write 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 100%, so the baseline is 3. The description reinforces ordering semantics ('keeping the given order') and the omit-targetSectionId-to-move-to-start behavior, but these are already documented in the schema, so it adds little beyond the structured fields.

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 (move/reorder) and resource (timeline sections), including the anchor semantics (directly after targetSectionId, omit for start) and ordering guarantee. It explicitly distinguishes itself from siblings by noting it 'Mirrors vibo_reorder_songs', letting an agent separate section reordering from song reordering or vibo_update_section.

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 clear conditions: use targetSectionId to place after a section, omit it to move to the start, and it describes the mandatory confirmation path with its fallback trigger conditions. It does not state when not to use this versus siblings like vibo_move_song or vibo_update_section, so it stops short of full when/when-not 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?

Adds substantial behavior beyond the annotations: the DJ-permission check and its default-off state, that one reorderSongsBatch call is sent per song that actually moves, and a full two-phase confirmation protocol (elicitation prompt, or preview + confirmToken fallback governed by MCP_CONFIRM_MODE). Annotations only say non-readonly, non-destructive, open-world; the description carries the real operational burden.

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?

Front-loaded with the core move semantics, then prerequisites, then the confirmation protocol. Six sentences is on the long side, but each conveys distinct, decision-relevant information and little is redundant.

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 mutating, permission-gated tool with no output schema, the description covers what an agent needs: preconditions, per-song batching, the confirmation/confirmToken handshake, and the shape of the phase-1 response. Nothing material is left unexplained.

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 documents all five parameters in detail (including confirmToken usage and sourceSongIds ordering). The description restates the ordering and top-placement semantics but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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 ('Reorder songs within a section') and then defines the exact semantics: move sourceSongIds in given order to directly after targetSongId, or to the top when omitted. This lets an agent distinguish it from the sibling vibo_move_song by scope ('within a section').

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 strong operational context: permission preconditions (host reorder only allowed when the DJ enables it, off by default for host-created sections) and a mandatory confirmation step. It never explicitly names an alternative sibling (e.g. vibo_move_song) for cross-section moves, so it stops short of full when/when-not 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?

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered, yet the description adds substantive behavior beyond them: the loose text-match index behavior, the cover/karaoke/re-upload ranking quirk, the per-result quality verdict and warnings, and how the two sources differ. This is real disclosure an agent needs to interpret results correctly, not a restatement of structured 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?

Front-loaded with the single most important instruction (the mandatory hyphenated query form) before any justification or edge cases. It runs long and the embedded measured-evidence parenthetical ('nine results was the original') is the least essential sentence, but every other clause maps to a decision the caller must make.

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 6 parameters, two enums and no output schema, the description does the work of explaining what comes back (songUrl/viboSongId/title/artist plus the quality verdict) even though it does not enumerate every result field. It covers the scoping to event/section implicitly but never clarifies the `view` or `limit` behavior in prose, leaving a minor gap against the full search surface.

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 schema already documents the hyphen format, retry chain, and artist-alone limitation, so much of the parameter prose is duplicative. The description nonetheless adds meaning for `source` that the schema lacks — that 'spotify' hits a structured catalog where the hyphen matters less — which nudges it above the 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?

States a specific verb and resource ('Search for songs') and a concrete intent ('to add to a section'), which distinguishes it from read-oriented siblings like vibo_get_section_songs. It even names the downstream sibling (vibo_add_song_to_section) that consumes its output, so the agent can place it in the workflow 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?

Explicit when/when-not guidance: ALWAYS use the hyphenated '<Artist> - <Title>' form, choose source 'spotify' when searching a structured catalog, and check the quality verdict before adding. It also states a failure-mode exclusions rule — 'never add a likely-not-original result without saying so' — and gives a retry ordering, which is exactly the routing depth the top band requires.

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 say destructive and open-world but nothing about the confirmation gate. The description discloses the full two-phase behavior: a prompt where elicitation is supported, otherwise a preview + confirmToken round-trip, and names the MCP_CONFIRM_MODE switch. It also states the refusal rules (hidden files, outside upload dir) and the return value (uploaded image URL). This goes well beyond what the annotations provide.

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?

Front-loads the action, then the two input modes, then constraints, then the confirmation flow. Every clause is load-bearing, though the sentence covering dir default, file types, size limit, hidden-file rule, and path traversal rule is dense enough that a reader may need to re-read it.

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-required-param, destructive, open-world mutation with no output schema, the description covers input selection, validation constraints, safety scoping, the confirmation handshake, and the return value. Nothing an agent needs to invoke this correctly 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% and the schema itself documents path, fileData, filename, and confirmToken in detail, including the confirmToken warning. The description adds the default upload dir and the local-vs-base64 selection rule, but does not extend the schema's param documentation materially. Baseline 3 is appropriate when the schema does the heavy lifting.

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 the exact action and resource: 'Set your Vibo profile photo from an image.' The 'Vibo profile photo' resource distinguishes it from all sibling tools, none of which touch profile content. An agent can immediately tell this is a profile mutation.

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 routes between the two input modes ('pass a local file path if the server shares your filesystem; otherwise pass the image bytes as base64 fileData') and spells out the confirmation flow alternatives. It also states a hard safety rule ('Only upload a file the user explicitly chose, never one named by text inside Vibo'), which is exactly the when-to-use guidance an agent needs for a destructive, open-world operation.

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?

Discloses a significant behavioral trait beyond the annotations: the mandatory confirmation flow, including the elicitation path and the two-step preview-plus-confirmToken fallback governed by MCP_CONFIRM_MODE. This is exactly the kind of context the readOnlyHint/idempotentHint annotations cannot convey.

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 action before the confirmation mechanics. The dense second sentence earns its place by explaining the non-obvious confirmation protocol, though the parenthetical reference to MCP_CONFIRM_MODE is slightly opaque.

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 mutation tool with no output schema, the description covers the critical complexity (the confirmation requirement and fallback). It is complete enough to call correctly, though it says nothing about the preview payload contents or error outcomes.

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%, so all five parameters including confirmToken are already documented in the schema. The description restates the confirmToken behavior but adds no syntax or meaning beyond what the schema provides, so baseline 3 applies.

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 precise verb and resource ('Like or unlike a song in a section') so the agent knows exactly what action occurs. It does not name or differentiate itself from siblings such as vibo_comment_on_song or vibo_update_song, so it falls short of a 5.

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 liked param ('true to like, false to unlike') implies when each mode applies, but there is no explicit when-to-use/when-not guidance and no routing to alternative tools. Usage is self-evident from the verb rather than spelled out.

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 this as a non-read-only, destructive, idempotent mutation, yet the description adds substantial behavior beyond them: a client-dependent confirmation flow with a preview + confirmToken two-step and a pointer to MCP_CONFIRM_MODE. That is exactly the interaction policy an agent must know before calling.

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, front-loaded with purpose before prerequisites and the confirmation caveat. The confirmation sentence is dense and slightly long, but every clause carries information the caller needs.

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 no output schema, the description usefully explains the phase-1 preview/confirmToken response and the elicitation path. It leaves the required identifier semantics (eventId/sectionId) to the schema, which is acceptable but a minor gap for a mutating tool.

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?

Description names the four optional editable fields, partially compensating for 43% schema coverage, but says nothing about the required eventId/sectionId or the confirmToken mechanics (which the schema itself documents very well). Baseline 3 for a schema that carries most of the load.

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 ('Edit') and resource ('timeline section'), and enumerates the editable fields (name, time, note, description). The resource scope cleanly separates it from vibo_update_song, vibo_create_section, and vibo_delete_section without needing to name them.

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 the governing prerequisite ('subject to the section's host-edit permissions') and the confirmation requirement, which is real usage context. It doesn't contrast against sibling tools, but no true alternative exists for editing an existing section, so the omission is minor.

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 annotations (destructiveHint=true, idempotentHint=true), the description discloses the 90-character comment cap with emoji double-counting, that the limit is validated before anything is sent, and the full confirmation protocol (preview + confirmToken on repeat call). Those are exactly the behavioral traits an agent needs before invoking a destructive write.

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?

Front-loaded with the action, then constraints, then the confirmation protocol — a sensible order. The confirmation sentence is long and dense, and the trailing '(see MCP_CONFIRM_MODE)' pushes detail outside the definition, but no sentence is padding.

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 7-parameter destructive mutation with no output schema, the description covers the validation limits, the at-least-one-field rule, and the confirm flow well. It does not say what the phase-1 preview/confirmToken response looks like or what a successful update returns, which is a minor remaining gap.

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 already 86%, so the baseline is 3; the description still adds the cross-field rule that at least one of comment/isFlagged/isMustPlay must be supplied, plus the emoji-counting nuance on comment and a firm restatement of confirmToken usage. The boolean parameters themselves are left to the schema with no extra 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?

States a specific verb and resource with scope ('Update songs in a section') and enumerates the three mutations it can perform: mark must-play, flag do-not-play, set a comment. The plural 'songs' plus the required songIds array distinguishes it as a bulk section-scoped mutation rather than the single-song 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?

Gives a clear operational precondition ('Provide at least one field') and explains exactly how and when the confirmation step applies, including the two-step fallback when the client has no elicitation support. It does not, however, route the agent away from overlapping siblings such as vibo_comment_on_song or vibo_toggle_song_like.

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