resolve_list_media

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

With no annotations, the description carries the full burden. It discloses that the tool lists clips, shows the current bin by default, supports navigating to a subfolder, and returns JSON with folder name, clips, and subfolders. This provides useful behavioral context. However, it does not explicitly state that it is read-only, nor does it mention error behavior or edge cases (e.g., invalid path). While it's obvious that listing is non-destructive, the lack of explicit safety information prevents a higher score.

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 two tightly scoped paragraphs. The opening line states the purpose, then it covers the parameter and return format without fluff. Every sentence earns its place, and the most important information is front-loaded. No redundancy with schema or annotations (since none exist).

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 tool is simple (one optional parameter) and the description covers the key aspects: default bin, navigation, and return structure. It mentions the JSON output includes folder name, clips, and subfolders, which is sufficient for an agent to know what to expect. There is an output schema present (though not shown), so the description need not detail every field. Minor gaps remain (e.g., exact metadata format), but overall it is complete for typical use.

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 does so excellently: the Args section explains that folder_path is optional, gives an example ('B-Roll'), and clarifies the default behavior when empty. This adds meaning well beyond the raw schema, which only has a type and default. All parameter semantics are covered.

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 states a clear verb ('List') and resource ('clips in the media pool') without ambiguity. It also specifies default behavior ('Shows the current bin by default'), which helps distinguish from other browsing tools. However, it does not explicitly compare with any sibling like resolve_find_media_clip or resolve_import_media, so it doesn't fully leverage sibling differentiation. Still, the purpose is immediately obvious.

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 implies usage via the folder_path parameter ('Navigate to a subfolder') and says 'Leave empty for current folder,' which gives context. But it does not explicitly state when to choose this tool over alternatives, nor does it mention any exclusions or prerequisites. For a simple list tool, the context is moderately clear but not fully explicit.

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