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

Annotations already provide readOnlyHint=true, so the read-only nature is covered. The description adds valuable behavioral context beyond the annotations: it states contents are not returned, which prevents the agent from expecting file data, and it clarifies the significance of the 'stub has finished reading it' state. It could also mention pagination or ordering, but for a read-only listing tool, the current disclosure is solid.

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?

Three dense sentences with front-loaded scope, a clear 'what you get' list, and a routing pointer to sibling tools. There is no filler, and every sentence earns its place.

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 read-only, zero-required-parameter listing tool with no output schema, the description tells the agent what fields come back, how to widen scope, and how to get file contents. The main gaps are output ordering/pagination and the precise meaning of the 'paired' filter in context, but the schema covers paired and the description covers the essential caller concerns.

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 100%, so the baseline is 3; the schema already documents folderid and paired. The description adds a little value by repeating the 'omit for all' semantics in prose, and it names the fields returned, but it doesn't add new parameter meaning beyond the schema. This is adequate, not exceptional.

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 begins with a clear resource ('The files in a folder') and enumerates what fields are returned (name, type, stub-read status, classification), which distinguishes this as a metadata-listing tool. It does not explicitly differentiate from sibling list tools like list_documents or list_binned, but the folder-scoped phrasing and the exclusions (contents are not returned) give it a reasonably distinct identity.

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 explicitly says 'omit folderid for every file' and tells the agent when to use read_file_columns and fold_file_column instead: when answers about what is inside a file are needed. This is clearer than most sibling definitions, though it does not explicitly enumerate other list tools or say 'use this only when folder-scoped file metadata is needed' as a hard exclusion.

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