smokeball_list_folders

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

Annotations already carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), lowering the burden on the description. The description adds genuinely useful behavioral context beyond the annotations: the governed-authority routing constraint and the note that Spring verifies the effect field must be 'read'. The approval_ref note about 'resuming a write' is slightly odd on a read-only tool but does not contradict the annotations.

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 short prose sentences followed by a tight 7-line Args block; every line earns its place given the 0% schema coverage. The routing constraint is front-loaded ahead of the parameter list. The phrasing is occasionally boilerplate ('Exact project correlation reference'), but overall the structure is efficient and scannable.

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 output schema covers return values and annotations cover safety, so the remaining burden is invocation semantics, which the parameter block largely satisfies. However, the inner 'arguments' JSON remains a black box — the description never hints at what arguments the list_folders connector operation actually accepts — and there is no guidance on when to select this tool over smokeball_search, smokeball_list_files, or smokeball_request. For a connector wrapper where the real payload lives in 'arguments', this is a meaningful 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?

With schema description coverage at 0%, the description fully compensates by explaining all 7 parameters: arguments as a JSON string, authenticated project UUID, exact project correlation reference, project-bound connector account alias, stable idempotency identity, the required read effect, and approval_ref for resuming writes. Minor deductions: the 'arguments' definition is circular ('JSON string of arguments'), and approval_ref's write-resume framing is confusingly placed on a read-only operation.

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 specific verb and resource — 'Smokeball connector operation `list_folders`' — and maps it to the platform tool `smokeball.list_folders`. This clearly identifies what the tool does and distinguishes it from generic folder-listing siblings (list_folder, clio_list_folders, document_intelligence_list_folder) by naming the Smokeball domain. However, it doesn't explain what a Smokeball folder is or how this listing differs from smokeball_search/smokeball_list_files, so differentiation rests mostly on the name.

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 sentence 'Routes only through the exact project/account governed connector authority' gives one meaningful usage constraint: this operation only works within the governed connector context of the exact project/account, which implies the agent must supply the matching project_id/connector_account_ref. But there is no explicit when-to-use/when-not-to-use guidance and no mention of alternatives such as smokeball_search, smokeball_integrated_search, or smokeball_request. Usage context is implied rather than stated.

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