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

The description fully discloses the confirmation behavior: a prompt where supported, otherwise a preview plus confirmToken flow, and explains the risk of adding a cover or karaoke track. It also notes that the tool writes (readOnlyHint=false) without contradiction. The MCP_CONFIRM_MODE reference adds practical context beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is multi-sentence but each sentence earns its place, covering the action, prerequisites, quality caution, and confirmation protocol. It is front-loaded with the primary purpose, though the quality-check and confirmation details add length. No redundancy is present.

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 operation with 7 parameters and no output schema, the description covers the essential flow: sourcing the song, verifying quality, and handling confirmation. It doesn't describe the success response format, but given no output schema, that's not mandatory. The description is complete enough for an agent to call the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 71% (5/7 parameters have descriptions), so the baseline is 3. The description adds significant meaning: it clarifies that songUrl is required and must come from search, and that viboSongId/title/artist should be included when known. Most notably, it explains the confirmToken's role and usage rules (never on first call, never invented), which goes well beyond the schema's brief descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a precise verb+resource: 'Add a song to a section.' It clearly differentiates from sibling tools like vibo_remove_song_from_section, vibo_update_song, and vibo_move_song by stating its specific action. The mention of the required songUrl from vibo_search_songs anchors the tool's role in the workflow.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly instructs to pass a song from vibo_search_songs, includes a quality check ('check that result's quality.confidence'), and advises against adding likely-not-original results, suggesting reporting matches instead. It also details the confirmation flow, including the two-step confirmToken fallback, which tells the agent exactly when and how to call the tool again.

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, it discloses file-upload restrictions (25 MiB limit, hidden files and out-of-directory paths refused), visibility of files to the DJ and event members, and the rule that only user-explicitly-chosen files may be attached. It also fully explains the confirmation/preview/confirmToken fallback behavior without contradicting the readOnlyHint and destructiveHint annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every sentence carries a distinct constraint or decision rule: question-type mapping, file-transport options, upload restrictions, visibility, and confirmation flow. The core purpose is front-loaded, and the caveats are sequenced logically rather than dumped as an unstructured block.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the high complexity of 12 parameters, no output schema, and no enums, the description covers every meaningful call decision: field selection, file transport, refusal conditions, and the confirmation token workflow. Nothing needed to invoke the tool correctly is left to guesswork.

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?

Although the schema already documents every parameter, the description adds the crucial mapping between question types and which field to provide, explains the otherOptionTitle relationship, and clarifies when imagePaths/filePaths versus images/files should be used. The confirmToken usage rules also go well beyond the schema's generic description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Answer a section planning question.' It immediately ties the tool to vibo_list_section_questions for option _ids, distinguishing it from list-only sibling tools and making it unambiguous that this is the action tool for responding to section questions.

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 strong conditional guidance: which parameter matches each question type, when to use local paths versus inline base64 files, and when the confirmToken two-step flow applies. It does not explicitly name excluded sibling tools, but there is no direct sibling for answering questions, so the guidance is sufficiently clear.

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

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

The description discloses the capture process, the need for the fetchproxy extension, the pair-code approval on first use, and that the token is saved locally and reused. It also clarifies it's for SSO accounts only. This goes beyond the annotations, which only say readOnlyHint=false and destructiveHint=false, and fully explains the behavioral side effects without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that front-loads the core action ('Capture your Vibo login...'), then adds necessary context about prerequisites and side effects. Every clause adds value—no filler. It is concise and information-dense, earning a top score.

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 setup tool with no parameters and no output schema, the description is fully complete. It explains what the tool does, when it's needed, the requirements (extension, signed-in tab), the first-use interaction (pair code), and the persistence behavior. 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?

The tool has zero parameters, so schema coverage is 100% (trivially). The description does not need to explain parameters; instead, it explains prerequisites and behavior. The baseline for 0 params is 4, and the description does not need to add parameter-specific info, so it's appropriately complete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool captures a Vibo login from a signed-in browser tab via a fetchproxy bridge, specifying the resource (login/session), the method (fetchproxy), and the condition (SSO accounts without password). It distinguishes itself from all sibling tools, which are about data operations, while this is the only session-capture 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?

The description implies when to use it: as a prerequisite for future calls, since it saves the token locally and reuses it. It also mentions the requirement of the fetchproxy extension and being signed in, providing clear context. However, it does not explicitly state 'use this before other Vibo calls' or name alternatives for password-based login, so it's not fully explicit.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, and the description adds substantive context beyond that: the tool always asks for confirmation first, it behaves differently depending on MCP_CONFIRM_MODE support, and the token must never be reused or invented. This meaningfully explains the safety mechanism around 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 dense sentences with no filler: the core action is front-loaded first, and the confirmation caveat follows. Every clause earns its place, compressing a complex two-phase protocol into a compact, readable form.

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 4-parameter mutation tool with a complex confirmation protocol and no output schema, the description covers the full calling protocol: required args, the elicitation-supported path, the fallback preview/confirmToken path, and token handling rules. Minor gaps remain — the success/failure response shape and token validity/expiry are unstated — but nothing blocks correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3 — the schema already documents eventId, userId, type, and gives an extensive confirmToken explanation. The description reinforces the confirmToken flow in prose but adds no net-new parameter-level meaning beyond what the schema already states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource — 'Change an event member's role between host and guest' — and enumerates the exact role values. This clearly distinguishes it from membership siblings like vibo_remove_user, vibo_invite_users, and vibo_join_event, so an agent can tell them apart 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?

The first sentence establishes clear use context: changing an event member's host/guest role. The second sentence provides precise procedural guidance on the two-step confirmation flow — when a confirmation prompt is used, when the preview/confirmToken fallback applies, and how the repeat call must carry the token. It lacks explicit exclusions or named alternatives, so it stops 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?

Beyond the annotations, the description discloses the critical confirmation behavior: a prompt where supported, or a preview/confirmToken flow requiring a second identical call without elicitation. This is essential operational context an agent could not infer from annotations or schema 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?

The description is two sentences with no filler. It front-loads the core action, then compactly explains the two confirmation modes and the confirmToken contract.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-step confirmation flow with no output schema, the description explains the first-call preview/confirmToken response and the required second call. It does not state what the final success response contains, but the call sequence an agent must execute is fully documented.

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 already carries a detailed explanation of its origin and constraints in the schema. The description reinforces the flow but does not add meaningful per-parameter semantics beyond what the schema provides.

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 phrase 'Leave a comment on a timeline section' states a specific action and target resource. The word 'section' clearly distinguishes this from sibling tools like vibo_comment_on_song and vibo_delete_section_comment.

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 makes the intended use explicit: commenting on a timeline section. It provides clear context but does not explicitly name alternatives or state when not to use it, stopping short of full 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?

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description discloses the important confirmation behavior: it asks the user first, and in fallback mode the first call returns a preview and confirmToken while only a repeat call proceeds. This is valuable behavioral context for a mutating tool and goes well beyond what annotations alone convey. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no fluff: the first states the purpose, the second explains the confirmation mechanism. It is front-loaded and every clause contributes. It is slightly dense due to the parenthetical 'see MCP_CONFIRM_MODE', but remains efficient and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's two-phase confirmation complexity and lack of an output schema, the description covers the critical invocation pattern: first call preview/confirmToken, repeat call with token, and client-supported prompt. It omits details about successful responses or failure states, but the schema and annotations cover safety and parameter requirements, making it sufficiently complete for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-level details beyond the schema, but it does contextualize the confirmToken within the two-step flow, which is already thoroughly explained in the schema. No additional semantic value for songId, eventId, sectionId, or message.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource: 'Leave a comment / note for the DJ on a specific song.' This clearly states what the tool does and distinguishes it from siblings like vibo_comment_on_section (section-level comment) and vibo_delete_song_comment (deletion). The purpose is immediately actionable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context ('on a specific song') but provides no explicit when-to-use guidance or exclusions relative to other commenting tools. It does not mention alternatives such as vibo_comment_on_section or when a song comment is inappropriate. Usage is inferred from the tool name and resource reference 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 only provide readOnlyHint=false and destructiveHint=false, which barely characterize behavior. The description goes well beyond that by disclosing the stateful two-step confirmation mechanism: 'a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken, and only a repeat call with that token proceeds'. It also explicitly says 'Add' which indicates a mutation, consistent with readOnlyHint=false. No contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no fluff. The primary purpose is front-loaded, and the confirmation behavior is explained succinctly in the second sentence. Every clause earns its place and no redundant information is present.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (8 parameters, a two-step confirmation flow, no output schema), the description covers the most critical runtime behavior and the confirmToken flow thoroughly. However, it does not clarify the optionality of name/phone fields, and the phrase 'with their name/email/phone' could mislead an agent into thinking name and phone are required when only email is required per the schema. Minor gaps remain, but overall it is sufficient for safe invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 63%, leaving lastName, firstName, and phoneNumber undocumented in the schema. The tool description adds the semantic grouping 'name/email/phone', which maps to these fields, but does not clarify which are optional or required beyond what the schema already states. The confirmToken parameter is well-described in the schema and reinforced in the description. The description adds some value but does not fully compensate for the undocumented parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific verb and resource: 'Add a contact (host or guest) to an event'. It explains the kind of data involved (name/email/phone). However, it does not explicitly differentiate this tool from sibling tools like vibo_invite_users or vibo_change_user_role, so it misses the highest level of sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides detailed mechanics for the confirmation flow (credential token fallback) but gives no guidance on when to use this tool versus alternatives. It does not state conditions, prerequisites, or mention any sibling tool (e.g., when to prefer vibo_invite_users instead). This leaves the agent without 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?

Beyond the destructiveHint annotation, the description reveals the critical two-phase behavior: the first call may only return a preview and confirmToken, and deletion only proceeds on a repeat call with that token. This materially changes how an agent should invoke the tool and prevents premature deletion.

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 purpose and followed by the essential behavioral nuance. No filler; every clause contributes to correct invocation.

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 tool with no output schema, this is complete: it covers confirmation, fallback token mechanics, and repeat-call conditions. Combined with fully described required parameters and destructiveHint, an agent has enough context to call it safely and 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%, so parameters are already fully documented, including confirmToken's origin and restrictions. The description reinforces the token flow but adds no new parameter-level meaning beyond what the schema provides.

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, 'Delete a comment on a timeline section,' uses a specific verb and resource, making the tool's function immediately clear. The 'timeline section' qualifier distinguishes it from sibling vibo_delete_song_comment without needing to open 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 explains the confirmation workflow: use a native confirmation prompt when supported, otherwise perform a two-step token flow. It does not explicitly name alternatives or exclusions, but the resource qualifier makes the intended use 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 already declare destructiveHint=true, so the destructive nature is known. The description goes further by detailing the confirmation protocol: it explains the two modes (client-supported prompt vs. two-step fallback with confirmToken) and explicitly states that a repeat call is required with the token. This adds significant behavioral context beyond the annotations, clarifying the exact interaction flow and the token's role.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long, with the core purpose ('Delete a comment on a song') front-loaded. The confirmation behavior is explained concisely without extraneous detail. Every word contributes to understanding the tool's function and its special confirmation handling.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the destructive nature, the description covers the critical confirmation behavior comprehensively. All parameters are described in the schema, and the description explains the two-step flow when needed. There is no output schema, but the description doesn't need to explain return values since the confirmation flow itself is the main behavioral nuance. For an agent to call this correctly, it has all necessary information: required IDs, the confirmation process, and the token handling.

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 parameters are already described in the schema. The description adds value by explaining the confirmation flow that directly relates to the confirmToken parameter, clarifying how and when it should be used. This goes beyond the schema's parameter-level descriptions, providing the overarching behavior that ties the parameters together.

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 the action 'Delete' and the resource 'a comment on a song', making the purpose unambiguous. It naturally distinguishes from the sibling vibo_delete_section_comment by specifying the song context. The verb-resource pair is specific and leaves no ambiguity about what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly implies the tool is for deleting song comments, but it does not explicitly mention alternatives or exclusion criteria. It also does not state prerequisites such as needing a comment ID from a prior call, though the schema covers that. The confirmation flow is described, which helps with when to call twice, but there is no explicit guidance on when not to use this tool versus other delete 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=false and destructiveHint=false already set, the description adds substantial context: the connection prerequisite, the return format (playlist URL + tracks exported/failed), and the full two-step confirmation protocol with confirmToken semantics. This goes well beyond the annotations' safety profile.

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 front-loaded sentences, each earning its place: purpose+prerequisite, return format, and confirmation behavior. Slightly dense but not bloated; the confirmToken explanation is lengthy but necessary for correct invocation.

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?

Covers the core function, prerequisite, return format, and the nuanced two-step confirmation flow with no output schema present. The reference to MCP_CONFIRM_MODE is a reasonable pointer to external context, leaving little ambiguity for a 5-param 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?

Schema coverage is 100% and each parameter already has a descriptive comment, including a detailed explanation of confirmToken's two-step fallback usage. The main description adds little beyond the schema, so the baseline 3 for high-coverage schemas 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 (export) + resource (event's song selections) + destination (new Apple Music playlist). It naturally distinguishes from the sibling vibo_export_event_to_spotify by naming the target service, so an agent can tell them apart at a glance.

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 prerequisite (Apple Music must be connected) and describes the confirmation flow that the caller must follow. It does not explicitly contrast with the Spotify sibling, but the tool name itself disambiguates the target platform, so the context is sufficiently clear.

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=false and destructiveHint=false, so the mutation nature is known. The description adds valuable context: it explains the two-step confirmation fallback with a confirmToken, references MCP_CONFIRM_MODE, and discloses that a preview is returned on the first call. This goes beyond the annotation hints and gives the agent a clear mental model of the call sequence.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, with the core purpose front-loaded. The second sentence is long because it must explain the confirmation protocol, but every part earns its place. It is not overly verbose and avoids redundancy with the schema, so it achieves good structure and efficiency.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of the confirmation flow and the absence of an output schema, the description fully covers what an agent needs to call this correctly: it states prerequisites, return values (URL and counts), and the two-step confirmation mechanism with clear instructions on when to pass confirmToken. It also references MCP_CONFIRM_MODE for further context, leaving no critical 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 100%, so every parameter already has a description. The tool description adds little beyond what the schema provides; the only extra is a brief mention of sectionIds sourcing from vibo_list_sections (already in the schema) and the confirmToken flow (also described in the schema at length). Thus the description does not meaningfully augment parameter semantics beyond the structured data.

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 starts with a specific verb-resource pair: 'Export an event's song selections to a new Spotify playlist.' This clearly distinguishes it from the Apple Music sibling (vibo_export_event_to_apple_music) by naming the target platform. It also states what the tool returns (URL, counts) and the confirmation flow, leaving no ambiguity about its function.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description specifies a prerequisite ('Spotify must be connected') and details the confirmation flow, but it does not explicitly contrast with the Apple Music sibling. However, by naming Spotify in the purpose, it implicitly guides the agent to use this tool when Spotify is the target, which is sufficient for a competent agent given the sibling list.

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, so the read-only safety profile is covered. The description adds useful context about what fields are returned, but it does not disclose additional behaviors such as error cases, authentication requirements, or response format. Given the annotations, this is adequate but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no filler. The main purpose is front-loaded with concrete field details, and the sibling pointer is compact and useful.

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-only tool with no output schema, the description sufficiently covers what the agent needs: what the tool does, what fields to expect, and which sibling to use for related data. Nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the eventId parameter already explains it is the _id from vibo_list_events. The tool description itself adds no parameter-level detail beyond that, so the baseline 3 applies because 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?

The description names the resource ('one event') and the specific verb ('Get full details'), then enumerates exactly what is returned: title, date/timezone, location, role, lock status, playlist size, and progress. This clearly distinguishes it from vibo_list_events (plural listing) and other sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The last sentence gives a direct routing hint: use vibo_list_sections when the timeline is needed, implying vibo_get_event does not provide the timeline. It does not exhaustively discuss when to prefer this over all siblings, but for its scope the guidance is clear and actionable.

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

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

The readOnlyHint annotation already signals a safe read operation. The description adds valuable behavioral detail about the view parameter's effect on the response shape—compact drops fields and strips avatar URLs, while full returns the payload untouched—which goes beyond the annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the core purpose and field list, and the parameter note is woven in efficiently. Every sentence carries information without redundancy or 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?

The description lists the expected fields and gives a concrete usage tip about the _id, which is helpful given there is no output schema. It could mention potential error conditions or authentication requirements, but for a simple read-only profile getter it covers the essential context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already documents the view parameter with an enum and description, giving 100% coverage. The tool description reinforces the default ('compact') and explains the practical consequence (stripping avatar URLs), adding a meaningful clarification beyond the schema's generic phrasing.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get', the resource 'signed-in Vibo user's profile', and enumerates the fields returned (id, name, email, phone, locale, Spotify/Apple Music connections). It also includes a practical usage hint about the returned _id, which helps distinguish it from tools that retrieve other users' data or events.

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 makes it obvious that this tool is for the current user's profile, and the hint about using the _id for recognition clarifies a typical use case. However, it does not explicitly state when not to use it or name alternative tools, though the sibling list implies that other tools handle different resources.

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

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

The description adds the specific behavioral detail that it returns the count of unread notifications, which goes beyond the readOnlyHint annotation. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One succinct sentence with no wasted words. Front-loaded with the core purpose.

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 parameterless read-only tool returning a simple count, the description is complete. No output schema is needed.

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?

No parameters exist; schema documentation coverage is 100% automatically. The description adds no parameter info, which is appropriate given there are none.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and the resource 'count of unread Vibo notifications', distinguishing it from siblings like vibo_list_notifications which returns the full list.

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 explicit guidance on when to use this tool vs alternatives (e.g., vibo_list_notifications). The usage is implied by the name, but the description could mention it's a lightweight alternative to listing notifications.

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

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

The annotations provide readOnlyHint=true, and the description adds the important auth/connection prerequisite: the source must already be connected, with a reference to vibo_get_me. This is useful beyond the annotation, though it doesn't describe return shape or rate-limit/paging 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?

Two sentences, no filler, and the core list action plus source scope are front-loaded. The clause about importing songs earns its place by signaling downstream use, and the prerequisite reference adds value without bloating.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only list tool with fully described parameters, the prerequisites, source enum, and purpose are covered. There is no output schema, and the description could more explicitly state what fields the agent will need from returned playlists for import, but the core information needed to call it correctly 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 the baseline is 3. The description reinforces source connectivity and names 'Spotify or Apple Music', but it does not add materially new parameter meaning beyond what the schema already documents for q, skip, limit, and source.

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 the specific verb 'List', the resource 'your playlists', and the scoped context 'from a connected streaming service (Spotify or Apple Music)'. This clearly separates it from siblings like vibo_get_playlist_songs, which targets songs within a playlist, and from import/export tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear usage context by stating the purpose ('so you can import songs from them') and the key prerequisite ('Requires that source to be connected'). It points to vibo_get_me for verification, but does not explicitly state when to prefer this over alternatives or exclude cases.

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

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

The readOnlyHint annotation already covers the tool's safety profile, and the description adds no further behavioral disclosure such as pagination details, connectivity requirements, or error behavior. The 'connected-service' scope constraint is mildly informative, but the description does not enrich behavioral transparency 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?

The description is a single clear sentence with no filler, and the key scope ('connected-service playlists') is front-loaded. This is appropriately concise for a tool whose parameter semantics are fully documented in the 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 simple read-only listing operation, the description plus fully documented schema gives an agent enough to invoke it correctly: source, playlistId, and paging controls are all covered. There is no output schema and the response shape is not described, but the tool name and 'List the tracks' make the return concept clear enough for selection and invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with each parameter already documented in detail: skip/limit defaults, the source enum with a connectivity note, and playlistId traced back to vibo_get_playlists. The tool description adds no parameter-level meaning, so the schema fully carries this dimension at the baseline level.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('List') and identifies the exact resource ('tracks in one of your connected-service playlists'), so an agent knows what the tool does. It is distinguishable from sibling tools like vibo_get_section_songs, though it does not explicitly name them, so it stops just short of full sibling differentiation.

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 explicit when-to-use guidance or 'use X instead' routing. The phrase 'connected-service playlists' implies the tool is for external streaming playlists rather than internal section content, and the schema's playlistId reference to vibo_get_playlists suggests a natural call sequence, but the description itself leaves usage selection largely implicit.

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

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

The annotations already declare readOnlyHint=true, so the safe read-only nature is covered. The description adds useful behavioral context beyond the annotations: it names the response fields a caller should expect and the supported sort dimensions. It does not discuss pagination or response shape nuances, but for a read-only list operation the description gives more than the structured annotations 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, front-loaded with the main action and resource, followed by the key sorting capability. Every clause earns its place: the field list tells the caller what the response contains, and the sort mention aligns with the sortField parameter. No filler or redundancy with the parameter 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?

Given a 10-parameter tool with no output schema, the description compensates by summarizing the main response content and sort behavior. Required parameters eventId and sectionId are documented in the schema, and the sectionId description even points to vibo_list_sections. A short mention of default pagination or the 'view' parameter would be marginally helpful, but the schema already covers those details.

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 70%, so the schema already documents most parameters including q, skip, limit, view, and filtering by flags. The description adds no new parameter-level meaning beyond mentioning the sort fields, which simply echoes the sortField enum already present in the schema. This meets the baseline for schema-covered parameters but does not exceed 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?

The description states a clear action ('List') and a specific resource ('songs requested in a section'), and it goes beyond a bare name by enumerating the returned fields: who added each, like counts, must-play / do-not-play flags, comments, and streaming links. It also narrows the scope enough to distinguish it from sibling list tools like vibo_list_section_song_ideas or 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?

The usage is implied: if you need songs in a section, this is the tool that lists them. However, it gives no explicit guidance on when to prefer an alternative such as vibo_list_section_song_ideas or when a filter like vibo_search_songs would be more appropriate. The sort options are stated, but alternatives and exclusions are not.

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?

Description adds context beyond annotations by specifying the return values (ok:true and account id) and authentication requirement, with no contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no wasted words, purpose stated upfront.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter read-only tool, description covers purpose, authentication, and return format completely, given annotations provide safety assurance.

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?

No parameters exist; description adds full meaning by describing tool behavior, meeting the baseline for zero-param tools.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the tool verifies connectivity and authentication by fetching the current user, distinguishing it from sibling tools that perform specific operations like listing or modifying events.

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?

Implied usage is for health checks before other operations, but lacks explicit when-to-use vs alternatives or when-not-to-use guidance.

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

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

Despite sparse annotations, the description discloses key behaviors: it is a mutating import that returns counts, requires user confirmation, and has a two-phase fallback where the first call returns a preview and confirmToken and only a repeat call with that token proceeds. This is substantial behavioral context 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?

Two dense sentences: the first states the purpose and outcome, the second explains the confirmation behavior. No filler, and the most important information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter import tool with no output schema, the description covers the return format, confirmation requirement, and fallback token mechanics. Combined with the rich per-parameter schema, an agent has enough to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the property descriptions are already detailed, including the source enum, token constraints, and provenance from sibling tools. The description adds the phase-1/phase-2 confirmToken lifecycle and the connected-account prerequisite, but most parameter meaning is carried by the schema, so this is modest added value beyond the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Import selected tracks from a connected Spotify/Apple Music playlist into a section.' It also names the return value ('counts of added/existing/ignored'), which distinguishes this batch import from sibling single-song and export tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear invocation context: source must be a connected Spotify/Apple Music playlist, and it explains the required confirmation flow ('Asks the user to confirm first'). It does not explicitly name alternatives such as vibo_add_song_to_section, so the 'when not to use' guidance is missing, but the context is otherwise 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?

The description goes well beyond the annotations by explaining the confirmation behavior: it asks the user to confirm first, returns a preview and confirmToken in fallback mode, and only proceeds on a repeat call with the token. It also explicitly warns that the token must not be invented or reused. This is strong behavioral disclosure beyond readOnlyHint/destructiveHint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two tight sentences. The first sentence states the action and the host/guest distinction; the second explains the confirmation behavior in both client modes. Every sentence earns its place, and the most important information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with five parameters, no output schema, and a nontrivial two-step confirmation flow, the description covers the essential behavior, including the fallback path and confirmToken lifecycle. It does not detail potential errors or result payload shape, but the confirmation-flow explanation is enough for an agent to invoke it correctly in most contexts.

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 input schema already has 100% description coverage for all five parameters, so the baseline is 3. The description reinforces the confirmToken flow, but the schema itself already documents the token's restricted usage. No additional parameter semantics are needed beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource: 'Invite people to an event by email (as host or guest).' This clearly differentiates it from sibling tools like vibo_join_event, vibo_leave_event, or vibo_remove_user. The confirmation-flow note adds precision without blurring the core purpose.

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 makes it clear that this tool is for inviting users by email and distinguishes the host vs guest use case. It also gives concrete usage context around confirmation behavior. It does not explicitly name alternative tools or state when not to use it, but the purpose is unambiguous enough that an agent can select it correctly.

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

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

The description goes well beyond what annotations provide, fully disclosing the confirmation requirement and the two-step fallback flow: first call returns a preview and confirmToken, and only a repeat call with that token proceeds. It also states the return value (joined event's id). This is critical, non-obvious behavioral context that the readOnlyHint=false / destructiveHint=false annotations do not convey, and it does not contradict them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each earning its place: the action, the return value, and the confirmation protocol. The purpose is front-loaded. The middle sentence is dense, packing both the prompt-supported path and the fallback path, but the complexity of the two-step flow justifies the length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple 2-parameter tool with 100% schema coverage, the description is nearly complete: it covers the action, the input format, the return value, and both confirmation modes, with a pointer to MCP_CONFIRM_MODE. Minor gaps remain, such as behavior on invalid/expired links or joining an event the user already belongs to, but these are edge cases rather than invocation-blocking omissions.

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%: both `link` and `confirmToken` already carry detailed descriptions, including URL/hash formats and the strict rules on confirmToken (never on first call, never invented, never reused). The main description adds little beyond the schema—it references the share-link mechanism but introduces no new parameter meaning—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?

The description states a specific verb ('Join'), resource ('event'), and method ('via its share link or hash'), which clearly distinguishes it from sibling tools like vibo_get_event, vibo_list_events, and vibo_leave_event. Citing the example URL format (vibodj.app.link/...) makes the action concrete and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'an event you were invited to' plus the mention of a share link establishes clear context for when the tool applies. However, it does not explicitly name alternatives or state when NOT to use it (e.g., to browse events use vibo_list_events, to view an event you already belong to use vibo_get_event).

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 provide destructiveHint=true, but the description adds valuable detail about the confirmation prompt and the two-step fallback with confirmToken. It explains the exact flow and references MCP_CONFIRM_MODE, which is beyond the annotation's binary flag.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences: the first states purpose and basic confirmation, the second explains the fallback. It is front-loaded with the primary action and efficiently covers the essential behavioral nuance without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive action with a confirmation mechanism, the description explains both the primary path and the fallback, including return behavior in the fallback. It lacks an output schema but the description covers what to expect. It is sufficiently complete for an agent 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 baseline is 3. The description adds meaningful context for confirmToken (never on first call, never invented, never reused, must match original args) that goes beyond the schema's description, reinforcing correct usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb (leave) and resource (event) with the condition 'previously joined', distinguishing it from siblings like vibo_join_event and vibo_get_event. It is specific and 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?

It implies when to use (if you previously joined the event) and implies not to use if you haven't, but does not explicitly name alternatives or exclusions. The confirmation flow guidance is clear, but the distinction from join_event is implicit rather than explicit.

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

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

Annotations provide readOnlyHint=true, so the description only needs to add non-safety behaviors. It adds the default behavior (upcoming vs past) and the optional search filter, which are behavioral nuances beyond the annotation. It does not mention pagination defaults, but those are already in the schema. No contradiction; adds useful context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core purpose, then behavioral defaults, then optional filter. Zero waste, each sentence earns its place. The structure makes it scannable for an agent.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a list tool with four parameters, no output schema, and read-only annotation, the description covers the essential behavior, defaults, and filters. Pagination parameters are documented in the schema. The description does not explicitly describe the return format, but for a list operation this is often self-evident; combined with the rich schema, the tool is adequately specified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds extra meaning by clarifying that 'past' defaults to false (via 'Defaults to upcoming events') and that the search query is optional ('Optionally filter by a search query'). This goes beyond the schema's descriptions, which state defaults but not the optionality emphasis. Adds value without redundancy.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb (list) and resource (events), with an explicit scope: 'events you're part of (as host or guest)'. This differentiates it from siblings like vibo_get_event (single event) and vibo_list_event_users (users in an event). The default behavior and optional filters further refine the purpose.

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 when to use the tool and how to adjust it: 'Defaults to upcoming events; pass past:true for events that have already happened.' It also mentions an optional search filter. While it doesn't explicitly contrast with alternatives, the purpose statement makes it clear this is the general listing tool, and the exclusion of single-event retrieval is implied. Clear context without exclusions.

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

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

Annotations declare readOnlyHint=true, and the description adds meaningful behavior: per-group pagination, merged vs. single-group return, and the difference between compact and full views. A minor inaccuracy exists ('id, name and role' vs. the schema's '_id, firstName, lastName, role'), but this does not contradict the annotations and overall behavior is well disclosed.

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 main action, and each clause carries essential information (modes, pagination, view options). No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only tool with no output schema, the description covers all key aspects: return structure for both modes, pagination behavior, and view options. It is complete enough for an agent to call it correctly without opening the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that limit/skip apply per group when usersType is omitted and what usersType does, going beyond the schema's basic descriptions.

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 ('hosts and guests on an event'), clearly distinguishing it from siblings like vibo_list_events (lists events) and vibo_get_event (gets event details). The purpose 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?

Provides clear context on how to use the tool by explaining the two modes (with/without usersType) and the view parameter. However, it does not explicitly mention when not to use it or name alternative tools, so guidance on choosing between siblings is implicit rather than explicit.

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

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

Annotations already declare readOnlyHint=true, so the read-only safety profile is covered. The description adds useful context by mentioning the response includes read state and linked event/section IDs, but it doesn't disclose ordering, pagination behavior, or whether the results are scoped to the authenticated user beyond the word 'your.'

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that names the resource, gives concrete examples, and notes the key response attributes. Every word earns its place; there is no filler or repetition of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple tool shape, no required parameters, and no output schema, the description gives enough return-value context by mentioning read state and linked event/section IDs. It could be more complete by noting default pagination or that the call returns the current user's notifications only, but the schema covers the call parameters and the annotations cover safety.

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 skip, view, and limit are already fully documented in the input schema. The description adds no parameter-specific meaning, which is acceptable given the schema's completeness, but it also doesn't compensate for any gaps or clarify defaults.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('List') and a clear resource ('your Vibo notifications'), and adds concrete scope: notification categories, read state, and linked event/section IDs. This distinguishes it from sibling tools like vibo_get_notifications_count, which would only return a count, and vibo_mark_notifications_read, which mutates state.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to choose this tool over alternatives such as vibo_get_notifications_count or vibo_mark_notifications_read. It states what the tool does but does not explain when listing is appropriate or how it relates to the sibling notification 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?

The readOnlyHint annotation already covers the safety profile, and the description adds meaningful behavioral detail by specifying the output contents: question types, options, answered state, current answer, and progress. It does not discuss ordering or pagination, but this is a simple read/list operation and the described output is sufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no filler. The main purpose is front-loaded, the return contents are compactly enumerated, and the follow-up tool reference earns its place by making the workflow actionable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the low complexity (2 required parameters), no output schema, and readOnly annotation, the description fully covers what the tool returns and how the result should be used next. It provides enough context for an agent to invoke the tool correctly and continue with vibo_answer_question.

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% for the two parameters, so the baseline is 3. The description adds value by explaining that sectionId comes from vibo_list_sections, which gives the agent provenance information beyond the schema's bare 'Section id' description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('List') and resource ('the DJ's planning questions for a section'), and enriches it with the exact content returned: question type, options, answered status, current answer, and progress. This clearly distinguishes it from siblings like vibo_list_sections and vibo_answer_question.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear operational context by stating that sectionId comes from vibo_list_sections and explicitly instructs to use the question _id (and option _ids) with vibo_answer_question. It does not list exclusions or alternative tools, but the downstream workflow is clear enough for an agent to decide when to call this tool.

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, so the agent knows this is a safe read. The description adds value by specifying the exact per-section fields returned: id, name, scheduled time, note, song count, and progress. It does not contradict annotations and provides useful behavioral detail beyond the title.

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 purposeful sentences with no filler. The first sentence front-loads the resource, examples, and return fields; the second adds actionable downstream guidance. Every element 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?

For a simple single-parameter read-only list tool, the description is complete: it identifies the input source, lists return fields, and explains how to use the output with sibling tools. No output schema exists, so the explicit field list is appropriately included.

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 input schema already provides 100% coverage for the single parameter eventId, including the note that it comes from vibo_list_events. The description's mention of 'an event's timeline sections' reinforces the parameter's meaning but adds no new syntax or format details. Baseline 3 is appropriate because the schema carries the semantic weight.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'List' with a clear resource 'an event's timeline sections', provides concrete examples (Ceremony, First Dance, Dinner, Dancing), and enumerates the returned fields. It distinguishes itself from siblings by naming the downstream tools that consume the section _id.

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 explicit downstream usage guidance: 'Use a section _id with vibo_get_section_songs / vibo_add_song_to_section.' This tells an agent what to do after listing, though it does not explicitly state when to prefer this tool over alternatives or mention negative cases. Context is clear, so it earns a 4.

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

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

The readOnlyHint annotation already covers the safety profile, and the description adds useful behavioral detail about the response shape (title, songsCount, _id). It does not mention pagination or edge cases, but those are largely covered by the schema and the tool is a simple read-only listing 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 with no filler. The core purpose is front-loaded, the return shape is included, and the follow-up workflow is stated efficiently. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a straightforward read-only listing tool, the description covers the purpose, the output fields, and the downstream workflow. The schema covers the optional paging parameters, and the readOnlyHint annotation covers safety, so nothing an agent needs to call this 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%, so all parameters (skip, limit, eventId, sectionId) are already documented in the schema. The description adds no new parameter semantics beyond implying that returned song-idea _ids will be used with another tool, 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?

The description opens with a specific verb and resource: 'List the DJ's suggested song-idea collections for a section.' It clarifies the returned fields and distinguishes the tool from related siblings by routing the song-ideas _id to vibo_list_song_ideas_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?

The description provides clear workflow context: list collections, then use the returned _id with vibo_list_song_ideas_songs, then add songs with vibo_add_song_to_section. It names the relevant sibling tools, though it does not explicitly state when not to use this tool or compare it to alternatives like vibo_get_section_songs.

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 provide readOnlyHint=true, so the safety profile is established. The description adds useful behavioral context beyond annotations by specifying the exact returned fields and their downstream purpose. No side effects, destruction, or rate-limit concerns are relevant for a read-only list 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?

The description is a single front-loaded sentence with no wasted words. It states the core action, the target resource, and the output contract all in one compact clause, making it easy for an agent to parse quickly.

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 fully described parameters and no output schema, the description provides enough context: what is listed, where it comes from, and what fields the caller will receive. The missing details such as paging and view modes are already covered by the input schema, so nothing critical 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 description coverage is 100%, so every parameter is already documented, including defaults, ranges, enums, and provenance of IDs. The description adds no new parameter semantics beyond naming output fields, which is not required because the schema already handles input meaning adequately.

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 and resource: 'List the suggested songs inside a song-idea collection.' It also clarifies what is returned and why it matters, naming the downstream tool vibo_add_song_to_section. This clearly distinguishes it from sibling list tools like vibo_list_section_song_ideas.

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 conveys the intended use case: retrieving suggested songs from a song-idea collection so their fields can be passed to vibo_add_song_to_section. It does not explicitly list alternatives or exclusions, but the workflow context is clear and sufficient for an agent to select this tool appropriately.

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

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

The description goes well beyond the annotations by explaining the confirmation prompt behavior and the two-step fallback with confirmToken. It discloses the exact flow a caller should expect, including the preview-first response and the requirement to repeat the call after user approval. This is excellent behavioral transparency.

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 main action and primary parameter choice are front-loaded, followed by the crucial confirmation behavior. Every phrase earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The confirmation flow, token semantics, and fallback behavior are thoroughly described, which is the most complex part of this tool. However, with no output schema, the final success response after a confirmed call is not explicitly described, leaving a small gap in what the agent can expect to return to the user.

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 input schema already has 100% description coverage, so the description adds value by explaining the relationship between notificationIds and readAll. It also embeds confirmToken usage into the overall flow, reinforcing the schema's warnings. Slightly more detail on edge cases like both parameters being provided would push this higher.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (mark notifications as read) and resource (notifications), and distinguishes it from sibling tools like vibo_list_notifications by focusing on the mutation. The two modes (specific IDs or readAll) further clarify exact purpose without ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context on when to use this tool: whenever notifications should be marked read, with guidance to pass specific IDs or use readAll. It does not explicitly name alternatives or exclusion conditions, but the tool's purpose is distinct enough from siblings that this is a minor gap.

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 sparse annotations, it discloses the two-phase confirmation behavior, including the fallback preview/confirmToken mechanism and the rule that only a repeat call executes the move. This is exactly the behavioral context an agent needs before invoking a mutating 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 with no redundancy: the purpose is front-loaded and the confirmation caveat is explained immediately after. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutating tool with no output schema, it explains the phase-1 response and the confirm-token handoff, and all parameters are covered by the schema. It does not describe the final success/error response after the confirming call, but the core call flow is sufficiently 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%, so the schema already documents all parameters. The description does not add parameter-specific semantics beyond the schema, meeting the baseline but not exceeding 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?

The description immediately states 'Move songs from one section to another,' identifying a specific verb, resource, and scope. It does not explicitly differentiate from sibling tools like vibo_add_song_to_section or vibo_remove_song_from_section, but the move action is clear enough to be understood.

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 confirmation procedure is described concretely: a first call returns a preview/confirmToken where required, and only a repeat call with the token proceeds. However, the description never states when to choose this tool over related alternatives, nor does it give 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 only flag the operation as destructive and non-read-only; the description goes well beyond by disclosing the confirmation-first behavior, the two-step fallback contract, and the exact lifecycle of confirmToken (never on first call, never invented, never reused). This materially changes how an agent must invoke the tool and is consistent with destructiveHint=true. No contradiction with 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 with the core action front-loaded and every sentence earning its place. The second sentence compresses the entire confirmation contract efficiently, though it is syntax-dense (colon plus semicolon) and slightly tangled, requiring careful parsing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the critical invocation flow — confirmation prompt where supported, otherwise the two-step token fallback — which is the main risk for a destructive tool. Gaps: no statement of what a successful removal returns and no error cases, and there is no output schema to fill that in. These are minor relative to the tool's core purpose.

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 eventId, sectionId, songIds, and confirmToken — including a detailed lifecycle contract on the token. The description adds no new per-parameter semantics 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 clause 'Remove one or more songs from a section' states a specific verb, resource, and scope, immediately distinguishable from siblings like vibo_add_song_to_section, vibo_move_song, and vibo_reorder_songs. The confirmation semantics that follow do not muddy the core purpose.

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 explicit guidance on when to choose this tool over alternatives such as vibo_move_song or vibo_add_song_to_section. What it does provide is detailed invocation guidance for the confirmation flow — first call returns preview and confirmToken, only a repeat call with the token proceeds — which is clear context but not tool-selection guidance. The usage of the tool itself is implied rather than stated as a decision rule.

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

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

The description goes well beyond the destructiveHint annotation by explaining the confirmation flow in detail: a prompt where supported, otherwise a preview plus confirmToken on the first call and a repeat call to proceed. This gives the agent important behavioral context that annotations alone do not 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?

The description is two sentences, front-loads the core action, and packs the necessary confirmation behavior into efficient prose. Every sentence adds value, with 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?

Given the destructive nature, the confirmation behavior is fully explained, including the fallback path and confirmToken lifecycle. With no output schema, the description still clarifies what the first call returns and how to complete the operation, which is sufficient for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with eventId and userId already described and confirmToken given a detailed explanation. The tool description adds context about the two-step confirmation flow, but it largely repeats the confirmToken semantics already present in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Remove a member from an event.' This clearly identifies the operation and distinguishes it from siblings like vibo_leave_event, which implies the actor leaving an event themselves.

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 action statement makes the primary use case clear, and the confirmation details describe how to invoke it. However, it does not explicitly mention when to prefer this over vibo_leave_event, vibo_change_user_role, or other member-related tools, nor does it give exclusions.

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

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

The description discloses a critical behavior not present in annotations: the tool requires user confirmation first, and in the fallback mode the first call only returns a preview and confirmToken, with the actual operation occurring only on a repeat call. This prevents an agent from assuming a single call completes the reorder. The reference to MCP_CONFIRM_MODE further clarifies the environment-dependent behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core action and then gives the essential confirmation behavior in a compact second sentence. Every phrase earns its place, and the reference to MCP_CONFIRM_MODE avoids restating external protocol details. It is dense but appropriately sized for the complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The confirmation protocol is the main non-obvious aspect of this tool, and the description covers both supported-client and fallback paths. Since there is no output schema, it also specifies that the first fallback call returns a preview and confirmToken. It could mention what a successful final call returns, but given the parameter schema's completeness and the explicit protocol, it is sufficiently complete for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the structured input documentation already explains eventId, sectionId, confirmToken, targetSongId, and sourceSongIds. The tool description mainly reiterates the confirmToken flow, which is already captured in the parameter schema. Therefore the description adds modest value but does not substantially improve parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource: 'Reorder songs within a section.' This clearly identifies the operation and scope, and distinguishes it from siblings like vibo_move_song by the 'within a section' constraint. The later confirmation details reinforce that this is a reorder action, not a generic update.

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 first sentence implies the tool is for reordering songs within a section, so the primary use case is clear. However, it does not explicitly compare against alternatives such as vibo_move_song, and there are no when-not-to-use or exclusion statements. This is implied rather than explicit guidance.

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

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

Beyond readOnlyHint, the description reveals the loose text-match index, cover/karaoke re-upload crowding, the empirical rank difference caused by hyphenation, the quality verdict/warnings on results, and source-specific catalog structure. These are behavioral traits not visible from annotations or schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description packs purpose, mandatory syntax, behavioral rationale, quality guardrails, source distinction, and return fields into a compact sequence with no filler. The empirical parenthetical is long but earns its place by justifying the critical query rule.

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 return fields and the downstream add tool. It covers the non-obvious behaviors (hyphenation, quality verdicts, source differences) and leaves schema-covered fields like limit and view to the schema. Nothing necessary for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already covers all 6 parameters at 100%, so the baseline is 3. The description adds extra semantics: mandatory query separator, the official-recording resolution behavior, and the meaning of source 'spotify' as a structured catalog. This nudges above baseline, but much of the query detail is duplicated from the schema, so it falls short of a 5.

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, 'Search for songs to add to a section,' states a specific action, resource, and intended downstream use. It also names the return fields for vibo_add_song_to_section, which distinguishes it from sibling list/get tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives imperative and conditional usage guidance: ALWAYS use 'Artist - Title' format, explains why via the searchField index behavior, and tells the agent to check quality verdicts before adding and to never add a likely-not-original result without disclosing it. It also distinguishes source 'spotify' as an alternative where the hyphen matters less.

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 indicate readOnlyHint=false and destructiveHint=false, but the description discloses much more: file type/size restrictions, rejection of hidden files or paths outside the upload directory, the requirement to only upload user-chosen files, and the confirmation flow with preview/confirmToken. It also notes the return of the uploaded image URL. This is strong behavioral transparency beyond structured annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense and front-loaded, but it is a single long paragraph with several compound sentences. While every sentence carries important information, the structure could be improved with line breaks or bullets for readability. It earns a 4 rather than 5 because it sacrifices light skimmability for completeness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (4 optional parameters, no output schema, minimal annotations), the description covers all necessary operating context: filesystem sharing condition, upload directory constraints, security rule (user-chosen file only), confirmation flow, and return value. It even references MCP_CONFIRM_MODE for clients needing the fallback. 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?

Although schema description coverage is 100%, the description adds crucial semantic context: the path/fileData selection rule, relative path resolution against VIBO_UPLOAD_DIR, allowed image formats, size limit, the filename default, and the exclusive two-step confirmToken semantics. It explains not just what each parameter is but when and how to use it correctly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a precise verb and resource: 'Set your Vibo profile photo from an image.' It immediately distinguishes this from the many sibling tools (events, songs, notifications) by naming the specific resource (profile photo). It also clarifies the two input modes (path vs fileData), making the tool's purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit conditional guidance: 'Pass a local file path if the server shares your filesystem; otherwise pass the image bytes as base64 fileData.' It specifies valid image types, size limit, upload directory rules, and when to use confirmToken for two-step confirmation. This fully covers when and how to use the tool without leaving the agent to infer from schema alone.

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

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

The description goes beyond the annotations by explaining the mandatory confirmation flow: the client-supported prompt, the two-step fallback with preview and confirmToken, and the requirement that the token be reused only after explicit user approval. This is essential behavioral context that annotations alone do not 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 carry exactly the needed information: the action in the first sentence and the confirmation mechanics in the second. No filler or redundant restatement of the 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?

The confirmation behavior, including the fallback path and token rules, is fully described, and all required parameters are documented with complete schema coverage. The main gap is the lack of a described success response for the final call, but the absence of an output schema is partially mitigated by the description of the phase-1 response.

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 are already fully documented. The description adds useful context about confirmToken's role in the two-step flow, but the schema itself also explains the token's usage, so the added value is marginal.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific action, 'Like or unlike a song in a section,' naming both the verb and the resource. This clearly distinguishes it from sibling song-related tools like adding, removing, updating, or commenting on 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?

The intended use is clear from the first sentence: the tool toggles a user's like state for a song. It does not explicitly name alternatives or exclusion conditions, but the narrow operation plus the confirmation requirement provides clear context for when to invoke it.

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 indicate readOnlyHint=false and destructiveHint=false, which are minimal. The description adds crucial behavioral context: the confirmation requirement, the two-step fallback with a preview and confirmToken, and the dependency on client elicitation support. This goes well beyond the annotations and is essential for correct invocation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no redundancy. The first sentence states purpose and permission, the second explains the confirmation flow. Information is front-loaded, and every clause serves a purpose without extraneous detail.

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 tool with no output schema, the description covers the most critical aspect—the confirmation mechanism—and explains the return behavior in the fallback case (preview and confirmToken). It also mentions permission constraints. It lacks details on success responses or error conditions, but given the complexity and the confirmation emphasis, it is sufficiently complete for an agent to 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 only 43%, so the description should compensate. It lists the fields (name, time, note, description) but does not define them beyond what the schema already provides for note and time. However, it gives detailed semantics for confirmToken, explaining its purpose, usage, and restrictions, which is valuable. The lack of elaboration on name and description keeps this at a 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool edits a timeline section's name, time, note, or description, using the specific verb 'Edit' and the resource 'timeline section'. It distinguishes from sibling tools like vibo_update_song by its focus on sections, and the listed fields make its scope unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not explicitly state when to use this tool versus alternatives, though the name and field list make it obvious for section editing. It mentions a permission constraint ('Subject to the section's host-edit permissions') but provides no exclusions or direct comparisons to sibling tools, leaving the decision to the agent's inference.

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

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

The description discloses the mutation behavior and the confirmation flow in detail, which is beyond the annotations (readOnlyHint=false, destructiveHint=false). It explains the need for user confirmation and the exact token semantics. A minor gap: it does not state whether updates are reversible or what happens to existing values when only some fields are provided, but the confirmation mechanism mitigates risk.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: it states the main purpose, then the prerequisite ('Provide at least one field'), then the confirmation flow. However, the confirmation flow explanation is long and could be split, but it is justified given the complexity. The main purpose is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (7 parameters, mutation, confirmation flow) and that there is no output schema, the description is complete for an agent to use it correctly. It explains the confirmation flow, the token usage, the requirement of at least one field, and the meaning of the optional parameters. An agent would not need to ask clarifying questions.

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 the description clarifies the purpose of the optional fields (comment, isFlagged, isMustPlay) and the confirmToken, which is not obvious from the schema. However, eventId and sectionId are only described as 'Event id' and 'Section id' with no additional context, but they are self-explanatory. The description adds value by explaining the confirmToken's role and the requirement to provide at least one field.

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 clear verb ('Update songs') and resource ('in a section'), and enumerates the specific update types (mark must-play, flag do-not-play, set comment). It is clear enough, but sibling tools like 'vibo_comment_on_song' and 'vibo_move_song' suggest overlapping functionality; the description does not explicitly distinguish itself from those, though the combination of fields is distinct.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states that at least one field must be provided and details the two-step confirmation flow, specifying when the confirmToken is required and when it is ignored. This is unusually thorough and gives the agent clear conditions for use.

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