browse_folder

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

With no annotations at all, the description carries the full burden. It does disclose a meaningful behavior beyond the name: results are what VLC itself sees through its file browser, which implies filtering or path-resolution semantics rather than a raw directory listing. It does not say whether the call is read-only (implied), how errors are returned for a nonexistent folder, or whether results are paginated or truncated.

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?

One front-loaded sentence stating the action, followed by a short Args block; nothing is redundant. The 'Args:' style is slightly inconsistent with a JSON schema but is clear and compact.

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 single-optional-parameter read operation with an output schema (so return values need not be explained), the description covers purpose and path semantics adequately. The missing pieces are error behavior for invalid paths and sibling routing, which are secondary for such a simple tool.

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, and it does: it explains that folder is interpreted relative to the video folder, that an empty value means the video folder itself, and that an absolute path is also accepted. The only gap is that the default of empty string is not restated and no path-format examples or failure modes are given.

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 and resource ("List the files and folders VLC sees in a folder") and clarifies the source is VLC's own file browser, which hints it differs from a plain filesystem listing or get_available_videos. It does not explicitly name a sibling, so the differentiation is implicit rather than spelled out.

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 says what the tool does but gives no when-to-use or when-not-to-use guidance, no mention of alternatives such as get_available_videos, and no exclusions. An agent must infer the choice of tool from the sentence alone.

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