browse

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

No annotations are provided, so the description carries the burden. It discloses that the tool returns top-level sources or descends into a given key, and implies the response contains browse_keys for further navigation. It doesn't explicitly state read-only behavior or side-effect absence, but the name and context imply a safe browsing operation. It doesn't mention rate limits or auth, but these are not typical for such a 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, front-loaded with the core purpose and then the key usage pattern. No redundant wording, and the most important information (modes of operation) comes first. 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?

The description covers the main workflow: listing top-level sources and descending via keys. It mentions the source of keys (previous browse or search_service), which is essential. While there is an output schema that likely details the return structure, the description doesn't cover edge cases or error conditions, but for a browse tool this is adequate. It's slightly incomplete in not mentioning that the player must be a valid one, but that's common knowledge.

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 must compensate. It explains the key parameter well: it's optional, can be null, and should be a browse_key from previous results. However, it doesn't add meaning for the player parameter beyond the schema's name, though it's self-explanatory from the tool's purpose. The description partially compensates for the coverage gap.

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 function: browsing a player's music sources, with two modes (top-level listing without a key, and descending with a key). It distinguishes itself from siblings by referencing browse_key from search_service results, implying navigation vs search, and its examples (TIDAL, TuneIn, Library) make the purpose concrete.

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: with no key it lists top-level sources, and with a key it descends. It also tells users to pass a browse_key from previous browse() or search_service() calls, giving a workflow. It doesn't explicitly contrast with alternatives like search_service, but the distinction is implicit in the key sourcing.

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