List service file uploads

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

Goes well beyond the annotations by disclosing required permissions, auth scope, refusal of execution-equivalent targets, availability reasons (agent_update_required, node_update_required, feature_disabled), and a 423 response for 2FA-locked servers. It also instructs the agent to relay unavailable reasons verbatim and never work around them, adding substantial behavioral context.

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?

The description is front-loaded: purpose first, then usage, permissions, and availability/error details. Each sentence carries operational information, though the paragraph is dense and could be slightly more structured for readability.

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?

Given no output schema, the description mentions the returned fields and covers permissions, availability, refusal behavior, and error codes. It provides everything an agent needs to call the tool correctly in this complex environment.

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% and the single orderNo parameter is fully documented in the schema with a pattern and example. The description adds no additional meaning about the parameter, so the baseline of 3 applies.

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?

States a specific verb ('List') and resource ('service's open uploads') with returned fields (received bytes, state, expiry). It also distinguishes itself from sibling tools by describing the triggering condition (filesUploadsLimit) and the follow-up action (abort stale uploads), making it easy to select against list_service_files or abort_service_file_upload.

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?

Explicitly says when to use it: when an upload answers filesUploadsLimit, to find stale uploads to abort. It also lists prerequisites (files:manage on FULL-access key, vm:files:write for hosted connector) and availability conditions. However, it does not explicitly name alternative tools or when not to use this one beyond the execution-equivalent refusal.

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