discover_players

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

The description discloses the network scanning behavior, protocol (SSDP/UPnP), and limitations across routers/VLANs and container setups. It implies a read-only operation and clearly states what will and will not be found, giving a transparent view of the tool's 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 and well-structured, covering purpose, return data, use cases, and network requirements in three sentences. It contains no redundant or extraneous 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 covers the tool's purpose, output fields, and operational constraints, which is sufficient for most callers. However, it does not explain the timeout parameter, and while an output schema may exist, the description's mention of returned fields helps fill the 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?

The only parameter, timeout, has no description in the schema and is not mentioned in the tool description. While its name and default value suggest a timeout in seconds, the description does not clarify units, effect, or whether it controls the overall scan duration or per-response waiting.

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 scans the local network for BluOS players via SSDP/UPnP and returns each player's name, host, port, and model. It also distinguishes this from configured players by noting it is independent of players.json, making the purpose 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 practical usage guidance, such as being handy for finding IPs to add to players.json or checking current network presence. It also notes the same-subnet requirement, which helps set expectations, though it does not explicitly contrast with sibling tools like list_players.

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