vibo_search_songs

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

Annotations already declare readOnlyHint=true, and the description adds meaningful behavioral context: the loose text match over a messy catalog, the impact of hyphenation on result ranking, the quality verdicts, and the warning check. This goes well beyond the structured annotation without contradicting it.

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 but every sentence earns its place: it front-loads the purpose and critical formatting, then provides evidence, quality guidance, source comparison, and return value context. It is well-structured with no wasted words.

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

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

The description covers purpose, query format, potential pitfalls, quality checks, source differences, and return values within the context of the next tool (vibo_add_song_to_section). It leaves no critical gaps for an agent to select and invoke the tool correctly, especially given the messy catalog domain.

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 all parameters are described, but the description enriches the query parameter with the hyphenated format, examples, and fallback strategies (reversing order or dropping to artist). It also adds context for source, explaining that Spotify's structured catalog makes hyphenation less critical. This is additive value on top of the schema.

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

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

The description opens with a specific verb and resource: 'Search for songs to add to a section.' It further distinguishes itself from the sibling vibo_add_song_to_section by stating it returns identifiers for that tool, and contrasts its two search sources (searchField vs spotify), making its role clear.

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

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

It provides explicit 'ALWAYS query as' formatting, explains when to use spotify versus the default searchField, and gives a rule for handling likely-not-original results ('never add... without saying so'). This offers practical guidance for both invocation and downstream steps.

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