list_file_requests

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

readOnlyHint=true already declares the safety profile, so the description's job is to add context, which it does by naming the required permission scope (shares:read) and disclosing that rows carry received file counts and cover only active requests. It does not say whether revoked or expired requests are excluded entirely or simply absent, which is the one remaining ambiguity.

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 sentences with no filler: the first identifies the resource and what its rows contain, and the second front-loads the authorization requirement. Nothing repeats the title or the annotations.

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 zero-parameter read with an output schema already describing the return shape, the description covers the only things an agent still needs: what a file request is and what scope it must hold. No behavioral or structural gap remains that would change how the call is made.

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?

The tool takes no parameters and the schema is a closed empty object, so there is nothing for the description to disambiguate. It does not misuse the space by inventing filters that do not exist, which would be a worse failure than saying nothing.

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 pairs a specific verb ("List") with a specific resource ("file request links") and then defines that resource as "anonymous upload links into a folder." That gloss is what lets an agent separate it from list_links or list_shares without opening a 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?

The word "active" implies the results are filtered to non-revoked requests, and the required scope is stated, which gives an agent enough context to decide it is the right listing call. However, there is no explicit when-to-use rule and no pointer telling the agent to prefer list_links or create_file_request under specific conditions.

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