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

With no annotations, the description carries the behavioral burden and does so well: archived objects are omitted, folders sort first, joins bypass folder filters, and signed_url is fresh/presigned and 'primary for agents' with an expiry. It stops short of stating pagination behavior (what to do past limit=200) or any permission/org-scoping constraints, which for a read tool is the main remaining gap.

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?

Purpose and scoping are front-loaded, but the middle block enumerating download_url, signed_url, signed_url_expires_in/at, share_url, public_url and the ``/d/{share_token}`` route is dense return-value detail that a declared output schema already covers. Those sentences crowd out more decision-relevant facts such as pagination.

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 6-parameter, zero-required list tool with an output schema, the description covers filtering modes, sorting, omission of archived rows, and URL semantics thoroughly. The notable omission is how to page beyond the 200-row ceiling (no cursor/offset mentioned in description or schema), which matters for an 'omit both to list every active object' 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 coverage is 83%, so baseline is 3; the description exceeds that by explaining interactions the schema cannot express — project_id overriding work_id, folder filters being ignored on attachment joins, 'root' meaning org root, and omitting both folder params meaning everything. The limit and query parameters are left to the schema, which is adequate at this coverage.

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?

Opens with a specific verb, resource and scope: 'List active Storage objects in the caller's org, newest first'. It also disambiguates from the nearest sibling at the end ('Transcripts stay on file_list(work_id=)'), so an agent can pick between storage_list and file_list without opening either schema.

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?

Gives explicit routing rules for each mode: work_id/project_id for attachments, parent_id/folder_id (or 'root') for a single folder, omit both to list everything, and file_list for transcripts. It even resolves the precedence case (project_id wins if both are set) and notes that folder filters are ignored on joins.

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