searchFind tracks, artists, or playlists by text query on HearThis, with page and count controls to browse audio-sharing results.
Search tracks, artists (users) or playlists by text.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page, starting at 1 | |
| type | Yes | ||
| count | No | Items per page (max 50) | |
| query | Yes |
Changes observed during successful MCP inspections.
v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and openness are covered. The description adds nothing about result ordering, matching semantics (substring vs. exact), pagination behavior, or the cost of broad queries, which are the traits an agent would need for this 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?
A single front-loaded sentence with zero filler. Nothing is redundant or buried.
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 response shape is entirely unknown, and the description does not say that results are paged, what fields are returned, or how many items appear. For a 4-parameter search tool with half its parameters undocumented, this leaves the agent guessing before and after the call.
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 50%: page and count are documented in the schema, while type and query are not. The description partially compensates by enumerating searchable entity types and clarifying that 'user' means artists, which genuinely helps map the enum value 'user'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (search) plus the resource types searched (tracks, artists/users, playlists), which is more precise than the bare title 'Search'. No sibling is a competing search tool, so no explicit differentiation is needed, but scope (text-based, entity-typed) is 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?
The phrase 'by text' implicitly contrasts this with id-based lookups like get_track, giving some usage signal. However, there is no statement of when to prefer this tool, no exclusions, and no mention of how to handle empty or ambiguous queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.