search_tracks

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

While no annotations are provided, the description clearly identifies this as a search operation that 'returns detailed track information' and explicitly states the return type as a dictionary. It does not fully disclose behaviors like pagination behavior, error handling, or whether it requires authentication (TIDAL login), but it is explicit about the search-and-return nature.

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 well-organized and front-loaded with a clear purpose and usage triggers. The example queries are useful, though they occupy several lines; every section earns its place. The Args and Returns sections are clear and 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?

For a 2-parameter search tool with no output schema, the description provides sufficient detail for an agent to invoke it correctly. It lacks explicit statements about authentication requirements, but sibling tools include tidal_login and get_listening_history, so the agent can infer the context. The description covers the essential call parameters and high-level return type.

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 0%, so the description carries the burden of explaining both parameters. It explains query as 'The search term (song title, artist name, or combination)' and limit as 'Maximum number of tracks to return (default: 20)'—both descriptions add meaning beyond the bare schema titles. It also notes that default limit is 20, which matches the schema's own default.

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—searching specifically for tracks/songs on TIDAL—with concrete query examples. It distinguishes itself from broader or different-content searches (albums, artists, playlists) through the explicit 'specifically for tracks' framing.

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 usage triggers ('USE THIS TOOL WHENEVER A USER ASKS FOR...') with concrete example requests, and clearly limits its scope to tracks/songs. Combined with the sibling-tool list showing separate search_albums/search_artists/search_playlists tools, the agent can route requests correctly.

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