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

The description discloses meaningful behaviors beyond the readOnlyHint=false annotation: it is confirm-gated and returns a preview without confirm=true, warns about likely-not-original results contaminating a live DJ set, and directs not to add a best guess. This is substantial operational context not present in annotations.

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

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

The description is front-loaded with the core action and each additional sentence adds essential context: source of the song, quality-confidence caveat, fallback behavior, and confirmation requirement. 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?

Despite having no output schema, the description covers the workflow, parameter provenance, safety (confirm gate and quality check), and failure behavior (report matches). This is comprehensive for a mutation tool integrated with search.

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 adds key parameter semantics: songUrl is required and sourced from vibo_search_songs, viboSongId/title/artist should be included when known, and confirm must be true to proceed. It does not elaborate on title/artist beyond inclusion, but overall it meaningfully supplements 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 'Add a song to a section', a specific verb and resource that clearly differentiates from siblings like remove_song_from_section or move_song. It further scopes the operation by requiring a song from vibo_search_songs, making the tool's role 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 explains when to use the tool (after searching songs) and provides guidance on checking quality.confidence before adding. It does not explicitly name alternative tools for excluded cases, but it instructs the agent to report matches back rather than add a best guess, which is clear behavioral guidance.

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

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

Annotations only provide readOnlyHint=false, so the description carries the burden of explaining behavior. It adds the confirm-gated behavior (preview without confirm) and the environment-dependent file handling (local paths vs base64). No contradiction with annotations, and the added context is valuable for the agent's decision-making.

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 five sentences and front-loaded with the main purpose. Each sentence contributes distinct information (field mapping, other-option handling, file delivery modes, confirm requirement). It is slightly long but dense and well-structured for a tool with 12 parameters.

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 (12 params, no output schema), the description covers the key decision logic: which field to fill, how to handle 'other', file path vs inline delivery, and the confirm gate. Required IDs are left to the schema, which is acceptable. It is complete enough 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%, giving a baseline of 3. The description raises the value by grouping parameters semantically (text, selectedOptions, link, otherOptionTitle, imagePaths/filePaths vs images/files) and tying them to question types. This mapping is not evident from the raw schema alone.

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

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

The description opens with a specific verb+resource: 'Answer a section planning question.' It clearly distinguishes this tool from the broad sibling list (e.g., vibo_list_section_questions) by explaining the exact response format mapping to question types. 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 gives explicit conditional guidance: which field to provide for each question type, when to use `otherOptionTitle`, and when to use local paths vs inline base64 ('when the server can read your disk... otherwise'). It also names the source for option IDs (vibo_list_section_questions). This is strong usage direction, even though no alternative answer tool exists.

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 explains behavioral traits beyond annotations: it requires a browser extension, saves the token locally, and reuses it on future calls. Annotations only provide readOnlyHint=false, so the description adds valuable context about the capture and storage behavior.

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

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

The description is concise (3 sentences), front-loaded with the action verb 'Capture', and includes essential prerequisites and behavior. Every sentence adds value without redundancy.

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

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

The description lacks explicit details about the return value or outcome after capturing the session (e.g., success indication, token confirmation). While the token is said to be saved, the user may expect to know what the tool outputs. Given no output schema, the description should cover this. The tool is simple, so this is a moderate 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?

With zero parameters, schema coverage is 100%. The description adds meaning by explaining that the tool captures the session from a signed-in browser tab, which is effectively the entire input context. A zero-parameter tool merits a baseline of 4, and the description fulfills that.

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

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

The description clearly states the tool's purpose: capturing a Vibo login session via fetchproxy for SSO accounts. It distinguishes itself from sibling tools (e.g., vibo_list_events) by focusing on session capture, which no other 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 provides clear usage context: it is for SSO login capture, requires the fetchproxy extension and being signed into web.vibodj.com, and explains the pairing process. However, it does not explicitly mention when not to use this tool or list alternatives, but given its unique role among siblings, 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?

Annotations indicate readOnlyHint=false, so this is a write operation. The description adds 'Confirm-gated,' disclosing that a confirmation step exists, which is not present in annotations. This alerts the agent to the two-step nature of the tool, though the specific preview behavior is documented in the 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 is extremely concise, consisting of two short sentences. It front-loads the core action and adds the critical confirm-gating note without any 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 mutation tool with a confirm gate, the description gives the essential purpose and the key behavioral trait ('Confirm-gated'). The input schema fully covers parameters, so the description doesn't need to explain them. The lack of an output schema is acceptable given the simplicity of the operation, though it could have mentioned the preview behavior explicitly.

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 fully documents all four parameters with descriptions and enum values. The description adds little beyond the schema: 'between host and guest' restates the enum, and 'Confirm-gated' hints at the confirm parameter but doesn't add syntax or detail.

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 ('Change') and resource ('event member's role'), and clearly identifies the two possible roles ('host and guest'). This distinguishes it from sibling tools like remove_user or invite_users, which have different actions on event members.

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

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

The description implies the tool is used when an event member's role needs to be toggled between host and guest, but it does not explicitly mention alternatives or when not to use it. No direct comparison is made to sibling tools like vibo_remove_user or vibo_invite_users.

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 indicate readOnlyHint=false, so the tool is a mutation. The description adds the 'Confirm-gated' behavior, but lacks other important details like authorization needs or permanence of the comment.

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

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

Two sentences, front-loaded with the action, no wasted words. 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?

For a simple 4-parameter no-output-schema tool, the description is adequate but lacks full context, such as what happens after confirmation (e.g., visibility, notifications). Could be slightly more informative.

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

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

Schema coverage is 100% with parameter descriptions. The description adds 'Confirm-gated,' which marginally clarifies the confirm parameter, but does not provide deeper meaning beyond the schema.

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

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

The description explicitly states 'Leave a comment on a timeline section,' which is a specific verb and resource. It clearly distinguishes from sibling tools like vibo_update_section by focusing on commenting.

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 guidance on when to use this tool versus alternatives such as vibo_update_section. The 'Confirm-gated' hint is present but does not provide explicit context or 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 only provide readOnlyHint: false, so the description carries the burden of disclosing behavioral traits. It adds that comments are directed 'for the DJ' and that the operation is 'Confirm-gated,' which implies a preview-then-confirm flow. This meaningfully supplements the annotations.

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

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

The description is two short sentences, front-loading the action and then adding the key confirmation trait. Every word earns its place with no redundancy.

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

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

With 5 parameters, 4 required, and no output schema, the description adequately covers the core purpose and the critical confirm-gating behavior. The schema handles parameter details. A minor gap is not describing what the preview returns, but the schema mentions a preview, so this is acceptable.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add parameter-level details beyond the schema; it only hints at the confirm parameter via 'Confirm-gated,' but the schema already explains that behavior more fully.

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 explicitly states the action: 'Leave a comment / note for the DJ on a specific song.' This uses a specific verb and resource, and the phrase 'on a specific song' distinguishes it from the sibling vibo_comment_on_section.

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

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

The description provides clear context by specifying the target is a specific song, which implicitly differentiates it from section comments. It also mentions 'Confirm-gated,' indicating the tool requires a confirmation step. However, it does not explicitly name alternatives or 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 adds the behavioral signal that the operation is 'confirm-gated,' meaning a preview is returned unless confirmation is provided. This goes beyond the readOnlyHint=false annotation by implying a two-phase write flow. However, it does not explain what the preview contains, what happens on duplicate contacts, or other side effects.

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

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

The description is a single, densely informative sentence with no filler. The core action is front-loaded, and the 'Confirm-gated' note is a compact, high-value behavioral qualifier placed at the end.

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 essential call path is covered: required eventId, role, email, and confirmation behavior are all inferable or stated. But with no output schema and no mention of what a preview returns or how optional name/phone fields behave, the description leaves some gaps for an agent executing a complete workflow.

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

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

The description maps 'name/email/phone' and 'host or guest' to the relevant schema fields, providing some cohesion across the 8 parameters. However, schema coverage is 63%, and the description does not compensate for undocumented fields like firstName, lastName, and phoneNumber, nor does it clarify optionality 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 clearly states a specific verb and resource: adding a contact to an event, with roles (host or guest) and fields (name/email/phone) enumerated. It is distinct from sibling tools like invite_users or remove_user because it focuses on adding a named contact to an event with confirmation gating.

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 context is implied: use this when adding a host/guest contact with their details. However, it does not explicitly distinguish this from sibling tools such as vibo_invite_users, nor does it state prerequisites or when not to use this tool. The confirm-gated note gives some procedural guidance but no comparative direction.

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:false, indicating a write operation. The description adds 'Confirm-gated', which informs the agent of a required confirmation step. However, it does not disclose additional behavioral traits such as irreversibility, permissions, or what happens without confirmation (though the confirm parameter description partially covers this). The added value is minimal but present.

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 short sentences, front-loaded with the main action and followed by a key detail. Every word earns its place; no redundancy or irrelevant information.

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

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

The description is adequate for a simple delete tool, but lacks explicit context about the confirmation flow (e.g., preview vs. actual deletion) and does not address potential irreversibility. The schema covers parameter details, but the description alone leaves some contextual gaps.

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

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

Schema coverage is 100%, with all four parameters described. The description adds no additional parameter semantics beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description clearly states the action: 'Delete a comment on a timeline section.' It uses a specific verb and resource, distinguishing it from siblings like vibo_delete_song_comment (song comment) and vibo_comment_on_section (adding a 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?

No guidance is given on when to use this tool versus alternatives. The description only states the function without context, exclusions, or reference to similar tools. The name implies scope, but the description itself does not provide usage direction.

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 explicitly discloses the confirm-gating behavior ('Confirm-gated'), which goes beyond the annotations that only state readOnlyHint=false. It also clearly indicates a destructive action ('Delete'), and there is no contradiction with the annotations. It does not detail the preview behavior when confirm is false, but the input schema fills that gap.

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

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

The description is extremely concise: two short sentences (or fragments) that clearly state the action and the gating behavior. Every word earns its place, with no fluff or repetition of the tool name.

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 delete tool with fully described parameters, the description is nearly complete. It clearly states the action and a key behavioral constraint, while the rich input schema covers parameter details. The lack of an output schema is acceptable for a delete operation, and the preview behavior is documented in the confirm parameter.

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 itself adds no additional parameter-level semantics beyond what the schema already provides. The confirm-gated note relates to the confirm parameter but is already explained in the schema's parameter 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 and resource ('Delete a comment on a song') that clearly distinguishes this from sibling tools like vibo_delete_section_comment, which deletes a section comment. The additional 'Confirm-gated' note immediately conveys a key purpose-relevant behavior.

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 use this tool versus alternatives such as vibo_delete_section_comment or vibo_comment_on_song. The only usage-related hint is 'Confirm-gated,' which is behavioral rather than contextual. No exclusions or alternative recommendations are mentioned.

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 significant behavioral context beyond annotations: discloses return format (playlist URL, track counts), confirm-gated two-phase execution, and no contradictions with readOnlyHint=false.

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 waste. First sentence states purpose, second sentence covers return and confirm-gated. Front-loaded and efficient.

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 5 parameters (2 required), no output schema, description covers return values, prerequisites, and confirm mechanism. Complete for its complexity.

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

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

Schema coverage is 100%, so baseline is 3. Description mentions confirm-gated behavior which explains the confirm parameter, but does not add substantial meaning beyond schema descriptions for other 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?

Description clearly states verb 'Export', resource 'event's song selections' to 'new Apple Music playlist', and differentiates from sibling vibo_export_event_to_spotify. 'Confirm-gated' further clarifies behavior.

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?

States prerequisite 'Apple Music must be connected' and confirm-gated nature. Implicitly distinguishes from Spotify export sibling but lacks explicit 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?

Annotations only indicate readOnlyHint=false, so the description adds meaningful context: the confirm gate (must set confirm=true), the Spotify connection requirement, and the return of exported/failed counts. This goes beyond the structured annotations and helps the agent anticipate side effects and prerequisites.

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 concise sentences that front-load the core purpose, then add critical behavioral details (Spotify connection, confirm gating, return value). No redundant or filler language 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 schema covers all parameter meanings and the description covers the core operation, prerequisites, confirm mechanism, and return value, the description is sufficiently complete for a mutation tool. It does not mention the preview behavior when confirm=false, but the schema already explains that, so the description remains adequate.

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

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

Schema coverage is 100% with all parameters described (eventId, sectionIds, title, confirm, onlyFlagged). The description adds no new parameter semantics beyond what the schema already provides, so it does not exceed the baseline for high schema coverage.

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

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

The description clearly states the verb 'Export' and the resource 'an event's song selections to a new Spotify playlist', explicitly naming Spotify to distinguish from the sibling Apple Music export tool. It also explains what the tool returns (playlist URL and export/failure counts), 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 provides clear context: this is for exporting to Spotify, requires Spotify to be connected, and is confirm-gated. It does not explicitly mention alternatives like vibo_export_event_to_apple_music, but the tool name and Spotify-specific scope imply when to use 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 already indicate readOnlyHint=true, and the description consistently describes a read operation. It adds specific details about the data returned (role, lock status, etc.), which is useful for the agent.

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

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

The description is one concise sentence that front-loads the main purpose and lists key fields. It is efficient but could use slightly more structure.

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 getter with one parameter and no output schema, the description lists the returned fields and mentions an alternative tool for timeline details, providing adequate 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?

Schema coverage is 100% and the schema already describes the parameter well. The description does not add extra detail about the parameter beyond what is in the schema.

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

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

The description clearly states the action 'Get full details for one event' and specifies the exact fields returned (title, date/timezone, etc.), distinguishing it from siblings like vibo_list_events which only list 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 explicitly mentions using vibo_list_sections for the timeline, guiding when to use an alternative tool. However, it does not directly compare to other event-related tools or state when not to use 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?

The readOnlyHint annotation already establishes the safe read-only nature, so the description does not need to restate that. It adds contextual value by enumerating the returned profile fields and the practical use of _id, but it does not disclose additional behavioral traits such as authentication requirements or failure modes. This is adequate but not exceptional.

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 with no filler. It front-loads the core action and resource, then adds the most immediately useful downstream instruction (recognize your own songs/contacts). 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 simple read-only profile retrieval with zero required parameters, a fully documented schema, and no output schema, the description covers what the agent needs: what the tool returns, how to use it, and a clear use case. 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 view parameter is thoroughly documented in the input schema, so the description does not need to compensate. The description adds no parameter-specific meaning, but the baseline of 3 applies because the schema already 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 a specific verb ('Get'), a precise resource ('the signed-in Vibo user's profile'), and enumerates the contained fields. It clearly distinguishes this from the sibling tools, none of which retrieve the current user's own profile.

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: whenever the signed-in user's own identity/profile is needed, and it instructs the agent to use the returned _id to recognize the user's own songs/contacts. It does not explicitly exclude alternatives, but no sibling tool serves the same purpose, so the guidance is sufficient.

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?

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds the requirement for a connected source, which is useful context. However, it does not mention error behavior, pagination, or result structure, so it provides only minimal extra 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?

The description is two sentences, front-loaded with the action and purpose, followed by a prerequisite. No unnecessary information is included, and it is well-structured for quick 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?

For a read-only list tool, the description covers the core action, prerequisite, and intended downstream use (import). However, lacking an output schema, it does not describe the returned playlist structure, which could be useful, but the simple nature of the tool makes this a minor gap.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description does not add significant semantic meaning beyond noting the source must be connected, which is also in the schema. 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 clearly states the tool lists playlists from a connected streaming service (Spotify or Apple Music) and explains its purpose ('so you can import songs from them'). This distinguishes it from siblings like vibo_get_playlist_songs, which retrieves songs from a specific playlist.

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 a clear prerequisite: the source must be connected, and it points to vibo_get_me for checking. It implies usage in the context of importing songs, but does not explicitly name alternatives or state when not to use it, so it falls 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?

The description adds value beyond the readOnlyHint annotation by specifying 'connected-service playlists', indicating authentication requirements. It does not contradict annotations and provides relevant behavioral 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?

Single, clear sentence with no wasted words. Front-loaded with 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?

No output schema, and description does not explain what the returned tracks contain (e.g., names, artists). Schema covers pagination but completeness is moderate for a list operation.

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

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

Schema description coverage is 100%, so the schema already fully documents parameters. The description adds no extra parameter semantics beyond the schema.

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

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

The description clearly specifies the action 'List' and the resource 'tracks in one of your connected-service playlists'. It is distinct from sibling tools like 'vibo_get_event' or 'vibo_export_event_to_apple_music'.

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 for obtaining tracks after retrieving a playlistId from 'vibo_get_playlists', but provides no explicit when-to-use, when-not-to-use, or alternatives. Limited guidance.

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

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

The readOnlyHint annotation already declares the read-only nature, and the description's 'List' wording aligns with that. The description does not reveal additional behavioral traits like pagination behavior or response shape beyond the parameter docs, though it also introduces no contradictions.

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

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

The description is a single concise sentence that front-loads the action and lists the important return fields. It contains no redundancy or fluff.

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

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

With no output schema, the description compensates by listing the key returned fields and available sort keys. It does not mention output paging metadata or default response shape, but the view and limit parameter descriptions cover some of that 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 describes most parameters, and the description adds useful meaning by naming the sortable fields (likesCount, createdAt, title) and mentioning must-play/do-not-play flags. However, sortDirection and isMustPlay lack schema descriptions and are not clarified further in the 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 clearly states the operation: listing songs requested in a section, and enumerates the returned data such as who added each song, like counts, flags, comments, and streaming links. This unambiguously distinguishes it from nearby mutation tools like vibo_add_song_to_section or vibo_remove_song_from_section.

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

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

The description explains what the tool does and even mentions sortable fields, but it does not explicitly say when to prefer this over alternatives such as vibo_list_section_song_ideas or vibo_search_songs. The only implicit guidance is the sectionId parameter pointing to vibo_list_sections.

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?

Beyond the annotation readOnlyHint=false, the description discloses that the operation is confirm-gated (requiring confirmation before proceeding) and returns counts of added/existing/ignored tracks. These are meaningful behavioral details that help the agent anticipate the tool's interaction pattern.

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 action, and every word contributes value. No redundant or filler content.

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

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

For a 7-parameter mutation tool with no output schema, the description covers the essential aspects: what it does, the return counts, and the confirm-gating behavior. The schema fills in remaining details like the preview behavior and source requirement, so the description 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?

All seven parameters have schema descriptions with 100% coverage, so the schema already provides parameter meaning. The description adds no new parameter-specific information beyond the word 'selected' mapping to tracksToAdd, which is marginal. 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 states a specific action ('Import selected tracks') with a clear resource ('from a connected Spotify/Apple Music playlist into a section'). It distinguishes itself from sibling tools like vibo_export_event_to_spotify (export) and vibo_add_song_to_section (single-song addition) by emphasizing playlist-to-section import.

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

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

The description implies the intended use case—batch-importing tracks from an external playlist into a section—but does not explicitly state when to use this tool over alternatives like vibo_add_song_to_section or when not to use it. The prerequisite of a 'connected' source is mentioned but not framed as an exclusion.

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

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

Annotations only declare readOnlyHint=false; the description goes a step further by flagging that the operation is 'Confirm-gated,' which tells the agent a confirmation token is required before the invite is sent. It stays consistent with the mutable nature of the tool and adds useful non-obvious 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 short sentences—first states the action and scope, second adds the key behavioral caveat. Every word earns its place and the most decision-relevant 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 five-parameter mutation with a complete schema and no output schema, the description plus annotations cover what an agent needs to select and invoke it: purpose, role dimension, and the confirmation gate. It does not describe response/error behavior, but no output schema exists and the schema already covers the preview case.

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 input schema already explains eventId, type, text, emails, and confirm. The description's mention of email, host/guest, and confirm-gating mirrors the schema rather than adding new parameter-level meaning, which meets but does not exceed 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 names a specific action ('Invite'), a clear resource ('people to an event'), the delivery channel ('by email'), and role scope ('as host or guest'). This is immediately distinguishable from sibling tools like vibo_join_event, vibo_change_user_role, and vibo_remove_user.

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 'Invite people to an event by email' establishes a clear use case, and the host/guest distinction clarifies what the type parameter is for. It does not explicitly name alternatives or exclusions, but no other sibling tool covers email invitations, so the routing context is sufficient.

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?

Describes join as a confirm-gated mutation, which aligns with annotations (readOnlyHint=false). Adds context beyond annotations: confirms gating behavior and return value.

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 main action. No fluff. Every sentence adds value.

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 key aspects: how to join, link format, confirm gate, return value. Lacks error handling but sufficient for core usage.

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%, baseline 3. Description adds meaning: link is a share URL or hash, confirm must be true to proceed. Clarifies the confirm parameter's role as a gate.

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?

Clear verb 'Join', specific resource 'event', method via share link/hash, and return value (event id). Distinguishes from sibling tools like vibo_get_event or vibo_leave_event.

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

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

Explicitly states when to use: to join an event you were invited to via share link. Implicitly excludes other actions but lacks explicit alternatives or when-not-to guidelines.

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 'confirm-gated' phrase discloses the confirmation behavior beyond the annotation's readOnlyHint=false. No contradictions; it adds useful context about the mutation.

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 short, direct sentences convey the essential information with zero waste. Perfectly 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 simple mutation tool with two parameters and no output schema, the description and schema together cover all necessary aspects: what action, on which resource, and with what safeguard.

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

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

Schema coverage is 100% with clear parameter descriptions. The description repeats the confirmation gate but adds no new details beyond the schema, so 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 clearly states the verb 'Leave' and the resource 'event', and the phrase 'you previously joined' distinguishes it from joining or viewing 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 indicates when to use (leaving a joined event) and the 'confirm-gated' note gives guidance on required confirmation. It implicitly excludes non-joined events but does not list alternatives.

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

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

Annotations already declare readOnlyHint=true, indicating a safe read operation. The description adds value by specifying the scope (events user participates in) and default filter (upcoming). However, it omits details like pagination behavior (skip/limit) or any effect on server state, which are not critical given the read-only nature but would enhance 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?

The description is two sentences covering purpose, default behavior, and optional filtering. Every word is functional, with no redundancy or extraneous detail. It is well-structured for quick comprehension.

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 absence of an output schema, the description adequately explains return context (list of events) and filtering capabilities. It does not explicitly mention pagination, but the skip/limit parameters in the schema imply that. For a read-only list tool with four well-documented parameters, the description 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 description does not need to explain each parameter. It mentions 'q' and 'past' in context but does not add meaning beyond what the schema already provides for skip/limit. A score of 3 is the baseline when schema is complete and description offers no extra insight.

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 lists events the user is part of (as host or guest), differentiating it from siblings like vibo_get_event (single event) and vibo_list_event_users (users of an event). The verb 'list' and resource 'events' are 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?

The description provides context on default behavior (upcoming) and how to get past events via 'past:true'. It also mentions optional search query filtering. However, it does not explicitly exclude scenarios or mention alternatives like vibo_get_event when details are needed, which would strengthen guidance.

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

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

Beyond the readOnlyHint annotation, the description reveals important behavior: the default merged response shape, the per-group pagination behavior, and the different behavior when usersType is supplied. This gives the agent a concrete mental model of what will happen without needing to call the tool.

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

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

Two sentences carry the essential behavior, response shape, and conditional pagination rules with no wasted words. The key call distinction is front-loaded in the first sentence.

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

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

Despite having no output schema, the description explains the default return shape and the usersType variant, while the input schema fully documents all five parameters. Combined with the readOnlyHint annotation, this is sufficient for an agent to select and 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?

Input schema coverage is 100%, so the baseline is 3. The description adds real semantic value by explaining how usersType changes the response and that limit/skip apply per group when usersType is omitted, which is more than the individual parameter descriptions convey.

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 hosts and guests on an event.' It adds conditional detail about the usersType parameter, making the tool's scope unambiguous and easily distinguishable from the many list-oriented siblings such as vibo_list_events or vibo_list_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 clearly conveys when to use the tool: to list event attendees, with an explicit fork for all users versus host-or-guest filtering. It does not name a particular sibling as an alternative or give exclusion criteria, but no sibling directly competes with this resource, so the usage context is clear enough.

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 read-only nature is covered. The description adds useful behavioral context beyond that by revealing the response includes read state and linked event/section ids, and by giving concrete notification categories, which helps the agent understand what will be returned in the absence of an output 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 is a single, front-loaded sentence that immediately states the action and resource, then packs relevant detail into a parenthetical without wasting words. Every part earns its place and there is no redundant repetition of the tool name or 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 low complexity of a list operation with no required parameters and a fully documented schema, the description is largely complete: it identifies the scope ('your'), the content categories, and the key response fields. However, since there is no output schema, a bit more detail about the exact return shape or ordering would make it fully comprehensive.

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

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

All three parameters (skip, view, limit) are fully documented in the input schema, including defaults, constraints, and the compact/full behavior of the view parameter. The description itself adds no additional parameter-level meaning, so the baseline of 3 is appropriate since the schema already carries the 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 begins with a specific verb and resource: 'List your Vibo notifications'. It adds relevant examples of notification types and states that the response includes read state and linked event/section ids, which clearly separates it from count-only or section-specific tools 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 usage context is implied: an agent should call this when it needs a list of the current user's notifications rather than a count or a mutation. However, it never explicitly names alternatives like vibo_get_notifications_count or vibo_mark_notifications_read, nor does it state when not to use this tool, leaving the routing largely 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?

Annotations declare readOnlyHint=true, so the read-only safety is covered. The description adds valuable detail about the response structure (question type, options, answered status, current answer, progress), going beyond the schema and annotations.

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

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

Two sentences, no filler. The first sentence packs the core purpose and output details, the second provides a cross-tool usage pointer. 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?

With no output schema, the description effectively documents the return value by enumerating fields. Combined with readOnlyHint and clear parameter guidance, the tool is fully specified for an agent.

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?

Both parameters have full schema descriptions (eventId, sectionId), and the description adds no additional parameter-specific meaning. The sectionId description already references vibo_list_sections, so 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 clearly states the tool lists DJ planning questions for a section, with specific fields returned. The verb 'List' plus resource 'section questions' distinguishes it from sibling tools like vibo_list_sections and vibo_get_section_songs.

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

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

The description provides workflow guidance by explicitly instructing to use the question _id and option _ids with vibo_answer_question, and the sectionId parameter references vibo_list_sections as a prerequisite. It lacks explicit alternatives but the cross-tool reference is strong.

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, and the description aligns with that. It adds specific behavioral context by listing the returned fields (id, name, scheduled time, note, song count, progress) and providing examples, going beyond the annotation. No contradictions detected.

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 just two sentences: the first states the purpose and output fields, the second gives downstream usage guidance. Every sentence earns its place, with no filler or redundancy.

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

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

Despite having no output schema, the description enumerates the return fields, making the data shape clear. The single parameter is documented in the schema, and the usage guidance links to related tools. For a simple read-only list tool, this 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?

The input schema fully describes the single parameter eventId, including its source (from vibo_list_events), giving 100% schema coverage. The description does not add parameter-level details beyond implying the event context. Baseline 3 is appropriate since 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') and clearly identifies the resource ('an event's timeline sections') with concrete examples (Ceremony, First Dance). It enumerates the output fields and explicitly references sibling tools (vibo_get_section_songs, vibo_add_song_to_section), distinguishing it from other listing 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 provides explicit guidance for next steps: 'Use a section _id with vibo_get_section_songs / vibo_add_song_to_section.' It also implies a workflow chain from vibo_list_events to this tool via the schema. However, it does not explicitly state when not to use this tool or contrast with other list tools.

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

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

The readOnlyHint annotation already declares this as a safe read operation. The description goes beyond annotations by specifying the return shape (title, songsCount, _id) and the contextual nature of the data (DJ's suggestions). No contradiction with annotations exists.

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 primary purpose, and every phrase adds value—return fields and downstream tool references. No 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?

Given no output schema, the description properly names the return fields (title, songsCount, _id) and explains the typical usage flow with sibling tools. Combined with the rich schema and annotations, this is a complete description for an agent to select and use 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?

The schema already provides full descriptions for all four parameters (eventId, sectionId, skip, limit), giving 100% coverage. The description does not add additional parameter semantics beyond the schema, which is acceptable per baseline criteria.

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 ('the DJ's suggested song-idea collections for a section') with a clear scope. It also names the return fields (title, songsCount, _id), distinguishing it from the sibling tool vibo_list_song_ideas_songs, which lists songs within a collection.

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 next-step guidance: after getting a song-ideas _id, use vibo_list_song_ideas_songs to see suggested songs, then vibo_add_song_to_section to add them. This clearly situates the tool within a workflow and differentiates it from related 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 communicates that this is a safe read operation. The description adds that it returns specific fields for downstream use, which is useful, but it does not disclose behavior such as pagination semantics, ordering, or response shape beyond the listed fields. With annotations covering the safety profile, 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?

The entire description is one sentence that front-loads the action and resource, then immediately states the return fields and their downstream purpose. There is no filler, repetition of schema details, or redundant annotation content.

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

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

For a read-only list tool with six parameters fully documented in the schema and no output schema, the description covers the essential return contract by naming the fields a caller needs. It could add ordering or pagination behavior, but the schema already documents skip/limit, and the readOnlyHint covers safety, so the definition is largely 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 all six parameters are already documented with descriptions, including defaults and enum behavior. The description's mention of return fields does not add parameter-specific meaning 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 description uses a specific verb ('List') and resource ('suggested songs inside a song-idea collection'), and adds the concrete return fields songUrl/viboSongId/title/artist. It does not explicitly contrast itself with sibling tools like vibo_list_section_song_ideas or vibo_get_section_songs, but 'song-idea collection' and 'suggested songs' make the target resource reasonably 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 phrase 'to pass to vibo_add_song_to_section' implies a downstream use case, so an agent can infer when this tool is useful. However, there is no explicit when-to-use guidance, no mention of when to prefer sibling list tools, and no exclusions or alternatives.

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

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

The description discloses that the tool is confirm-gated (without confirm:true, no action is taken) and that readAll:true clears all notifications. These are behavioral details beyond the readOnlyHint=false annotation, adding meaningful context about side effects and verification.

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 concise sentence with a short second clause, front-loading the core action and the two usage options. Every word earns its place with no redundancy.

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

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

For a simple state-change tool with well-documented parameters and a readOnlyHint=false annotation, the description covers the essential usage modes and the confirm requirement. It omits return value details, but no output schema exists and the schema already documents the confirm behavior, so the description is sufficient.

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

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

The input schema already provides 100% description coverage for the three parameters, including the confirm preview behavior and the meaning of readAll. The description adds no additional parameter semantics beyond what the schema already documents.

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 ('Mark') and resource ('notifications as read'), clearly indicating a state-changing operation. It distinguishes itself from read-oriented siblings like vibo_list_notifications and vibo_get_notifications_count by making the mutation explicit.

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 explains the two primary invocation modes (specific notificationIds or readAll:true), and mentions the confirm gate, giving clear context on how to run the tool. However, it does not explicitly state when not to use it or reference alternative tools, so it lacks full exclusion guidance.

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

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

The description adds the 'Confirm-gated' trait, which is not present in the annotations, providing useful context that the tool requires a confirmation step. However, it doesn't elaborate on what happens without confirmation (preview) or any side effects beyond the move itself.

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 two-sentence summary (the second a fragment) that delivers maximum information with minimum words. It is well-structured and 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?

The schema covers all parameter details, and the description adds the confirmation gate flag. However, the absence of an output schema and the vague 'Confirm-gated' leave the agent without information about what the preview looks like or how confirmation should be handled.

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?

All five parameters have descriptions in the schema, so the baseline is 3. The description doesn't add any extra semantics about parameters; it only refers to 'songs' generically.

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 ('Move') and resource ('songs') with explicit source/target sections, making the tool's purpose unmistakable. It is distinguishable from siblings like add/remove by the inherent 'from...to...' phrasing, though it doesn't explicitly name alternatives.

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 offers no guidance on when to choose this tool over add_song_to_section or remove_song_from_section. The 'Confirm-gated' note hints at invocation flow but doesn't explain the two-step preview/confirm process, which is left to the schema.

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 'Confirm-gated' behavioral trait, which is not present in the annotations (only readOnlyHint=false). This signals the need for a confirmation step and hints at destructive potential. It adds value beyond the structured annotations, though it could mention the preview 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 short, front-loaded sentences with zero filler. The core action and the critical confirm-gating behavior are stated efficiently. Every word earns its place.

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

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

Given no output schema and minimal annotations, the description is adequate but sparse. It mentions confirm-gating but doesn't explain the preview behavior or return format, leaving the agent to rely on the schema. More context on the destructive nature or workflow would improve completeness.

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 no new parameter semantics beyond reinforcing 'one or more songs' (already implied by songIds array with minItems:1). No additional detail on formats or relationships is provided.

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 identifies the action ('Remove') and the resource ('one or more songs from a section'). This distinguishes it from sibling tools like vibo_add_song_to_section or vibo_move_song. The scope is explicit 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 description implies a clear use case but does not explicitly contrast it with alternatives like vibo_move_song or vibo_reorder_songs. It lacks explicit 'when to use this vs. other tools' guidance, though the 'Remove' purpose makes the context obvious.

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 indicate readOnlyHint=false, so the mutating nature is known. The description adds the behavioral detail 'Confirm-gated', which clarifies that confirmation is required and implies a preview or dry-run step, beyond what the annotation provides.

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

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

The description is two short sentences, with no filler words. 'Remove a member from an event.' provides the core action, and 'Confirm-gated.' adds a critical behavioral note efficiently.

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 (3 params, no output schema), the combination of description, annotations, and full schema coverage provides sufficient information. The description lacks explicit return behavior, but the schema's confirm parameter description covers the preview behavior.

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 (userId, confirm, eventId) having clear descriptions. The tool description adds no additional parameter semantics, so 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 uses the specific verb 'Remove' with the resource 'a member from an event', clearly stating the action. It is distinct from siblings like vibo_leave_event (which implies self-removal) and vibo_change_user_role (which alters roles rather than removing).

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 for removing a member from an event but does not explicitly distinguish it from vibo_leave_event or state when not to use it. The 'Confirm-gated' note hints at the confirmation requirement, but no explicit alternatives or prerequisites are given.

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=false, so the write nature is known. The description adds 'Confirm-gated', which is a behavioral trait beyond the annotation, but this is also described in the schema's confirm parameter. No additional side effects, reversibility, or permission requirements are 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?

The description is a single concise sentence that immediately states the purpose and a key trait. It is not a tautology and contains no unnecessary words, though it could be slightly more informative without losing 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?

For a mutation tool with a confirmation flow, 5 parameters, and no output schema, this description is under-specified. It lacks guidance on the preview/confirm workflow, target placement semantics, and does not reference sibling tools or edge cases, leaving the agent to infer critical 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?

Schema description coverage is 100%, so the baseline for parameter semantics is 3. The description adds no extra meaning beyond what the schema already provides; it does not explain the relationship between sourceSongIds and targetSongId or the preview behavior beyond the schema.

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

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

The description states a specific verb ('Reorder') and resource ('songs within a section'), making the primary action clear. However, it does not distinguish itself from the sibling tool 'vibo_move_song', which likely performs a similar single-song operation, so it lacks explicit 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?

No guidance is provided on when to use this tool versus alternatives like 'vibo_move_song' or 'vibo_remove_song_from_section'. The confirm-gated behavior is hinted but not explained as a usage prerequisite, and there is no mention of prerequisites or context.

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

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

Beyond the readOnlyHint annotation, the description reveals substantial non-obvious behavior: the searchField index is a loose text match over a catalog polluted with covers and karaoke tracks, the hyphenated form changes ranking outcomes (backed by a measured live result), results carry quality verdicts, and there is an explicit safety rule about never silently adding likely-not-original results. This is exactly the behavioral context annotations cannot convey.

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

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

The description is dense — roughly 160 words — but every sentence earns its place: the ALWAYS rule is front-loaded, the empirical anecdote justifies an otherwise suspiciously strong directive, and the quality-verdict warning addresses a real safety concern. Slightly long for a search tool, but none of the content is filler.

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

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

There is no output schema, yet the description handles the burden: it states the returned fields (songUrl/viboSongId/title/artist), the quality verdicts on results, the source-specific behavior, and the downstream consumer (vibo_add_song_to_section). For a 6-parameter search tool this is complete — nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents every parameter, placing the baseline at 3. The description adds value on top: it elevates the query parameter's format to an 'ALWAYS' rule with empirical evidence the schema lacks, explains why the source parameter matters (structured Spotify vs loose searchField index), and links the query outcome to downstream safety checks. This is meaningful enrichment rather than mere restatement.

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

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

The description opens with a specific verb+resource: 'Search for songs to add to a section.' It is immediately distinguishable from siblings like vibo_add_song_to_section (which adds rather than searches) and vibo_list_section_songs/vibo_get_section_songs (which list existing state rather than search). The scope is clear and the tool's role in the workflow is named.

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

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

Usage guidance is exceptionally explicit: the ALWAYS rule for query formatting is stated first, with a concrete example, empirical justification, and the specific failure mode it prevents. It also gives fallback strategies ('retry as "<Title> - <Artist>"' then title-only), and a source-selection rule (spotify vs searchField), so an agent knows exactly when and how to invoke the 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 only declare readOnlyHint: false (a write operation). The description adds meaningful behavioral context by mentioning 'Confirm-gated' and that it 'Returns the uploaded image URL'. This goes beyond the annotation by disclosing the confirmation requirement and return value, though it does not explicitly explain the preview behavior without confirmation (covered in the 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 is two sentences: the first states the purpose, the second explains input options and output. There is no redundant wording, and it is front-loaded with the most important information. Every sentence earns its place.

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

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

For a file-upload tool with no output schema, the description covers the essential elements: purpose, input method selection, return value, and confirmation gating. It lacks an explicit mention that without `confirm=true` the tool returns a preview, but the schema parameter description provides that detail, so overall completeness is high but not maximal.

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 a baseline of 3 applies. The description adds value by explaining the decision rule between `path` and `fileData` based on filesystem sharing, and clarifies that `fileData` is base64-encoded image bytes. This semantic context is not present in the schema itself.

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 begins with 'Set your Vibo profile photo from an image', which uses a specific verb ('Set') and resource ('Vibo profile photo'), clearly stating the tool's core purpose. It distinguishes itself from all sibling tools, none of which relate to profile photo changes, making its function 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 provides clear guidance on when to use `path` versus `fileData`: use `path` if the server shares the filesystem, otherwise use `fileData`. This is practical context for tool selection. It does not mention alternatives because no sibling tool serves the same purpose, so the lack of explicit 'when-not-to-use' is acceptable.

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 'Confirm-gated' which highlights the confirmation requirement and preview behavior, complementing the readOnlyHint=false annotation. It does not describe auth expectations or error states, but the toggle behavior is clear.

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 only two phrases, highly efficient and front-loaded with the primary action. Every word contributes to understanding the tool's core behavior.

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

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

The tool is simple and the schema covers parameters, but the description lacks details about the preview behavior, return values, or any side effects beyond the toggle. Confirm-gating is mentioned but not elaborated, leaving some ambiguity about the interaction flow.

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?

All five parameters are already described in the schema with full coverage. The description adds no additional parameter semantics beyond the schema, so baseline 3 applies.

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

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

The description clearly states a specific action ('Like or unlike') on a specific resource ('a song in a section'), distinguishing it from sibling tools like vibo_add_song_to_section or vibo_remove_song_from_section. The mention of 'Confirm-gated' adds a unique behavioral identifier.

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 when-to-use or alternative comparisons are provided. The description implies the tool is for toggling a song's like status, but does not differentiate it from vibo_update_song or note any prerequisites. Slight gap in guidance.

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

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

The description adds behavioral context beyond annotations: it notes permission requirements ('Subject to the section's host-edit permissions') and the confirm-gating behavior (implies a two-step process). This complements the readOnlyHint=false annotation 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 extremely concise: two sentences that cover the purpose, permissions, and confirm-gating without any extraneous content. Every sentence is necessary.

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

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

Given the tool has 7 parameters, no output schema, and moderate complexity, the description provides essential info (permissions, confirm-gating) but omits details about the preview behavior, expected response, or error conditions. It is adequate but not comprehensive.

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

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

Schema description coverage is 43% (3 of 7 parameters have descriptions). The description enumerates editable fields but adds no extra semantic details (e.g., format, constraints) for undocumented parameters like 'name' and 'description'. For a low-coverage scenario, the description insufficiently compensates.

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 ('Edit') and the resource ('a timeline section') and lists the editable fields (name, time, note, description). It distinguishes itself from sibling tools like vibo_comment_on_section by focusing on updating section properties rather than commenting.

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 usage context: it is subject to host-edit permissions and is confirm-gated (requires confirm parameter to execute, otherwise previews). However, it does not explicitly state when to use this tool vs. alternative tools (e.g., for different section operations).

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 meaningful behavior beyond the readOnlyHint=false annotation: it discloses the confirm-gating mechanism and that a preview is returned when confirm is not true. It also clarifies that at least one field must be provided. 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 tight sentences: the first identifies the action and supported operations, the second covers essential constraints (at least one field, confirm-gating). No unnecessary words.

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

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

The tool has 7 parameters, no output schema, and moderate complexity. The description adequately covers purpose, key constraints, and confirmation behavior, but it does not mention whether isMustPlay and isFlagged can be set together or what the preview shows. These gaps are minor given the schema and annotations.

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 71%, leaving isMustPlay and comment without descriptions. The tool description fills this gap by mapping these fields to 'mark must-play' and 'set a comment', and by explaining the confirm parameter's role via 'Confirm-gated'. This adds value beyond the schema.

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

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

The description clearly states the tool updates songs in a section and lists the exact operations: mark must-play, flag as do-not-play, and set a comment. This specific verb+resource combination differentiates it from sibling tools like vibo_comment_on_song or vibo_toggle_song_like.

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 (updating songs in a section) and states the 'Provide at least one field' and 'Confirm-gated' requirements. However, it does not explicitly name alternatives or say when to use this tool instead of related tools, so usage guidance relies on implication.

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