browse

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed world), yet the description adds real value beyond them: item field contents (name, path, uri, kind, is_loadable, is_device), pagination behavior, and case-insensitive matching. No error behavior for bad paths is described, so it stops short of a 5.

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?

A tight, front-loaded paragraph with no filler; the path convention is stated first and the return fields/paging follow. Slightly dense with parenthetical asides, but every clause carries 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?

With no output schema and 0% parameter coverage, the description compensates by enumerating returned item fields and paging mechanics. It lacks failure modes (invalid/nonexistent path) and any note about ordering, but is otherwise sufficient for correct invocation.

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 and mostly succeeds: it explains path syntax/semantics (root "", nested example, case-insensitive names, optional extensions) and the paging role of limit and offset. It doesn't document limits on limit values or offset defaults beyond what the schema shows.

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?

Clear verb+resource ("List a browser folder") with concrete path examples that make the scope unambiguous. It implicitly separates itself from siblings like search_browser and load_from_browser, but never names or contrasts them explicitly.

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 root-path convention ("" lists categories) and example path give implied usage, and paging with limit/offset is explained. However there is no explicit guidance on when to choose browse versus search_browser or how it pairs with load_from_browser, leaving the workflow to inference.

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