list_archive_files

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

No annotations are provided, so the description carries the burden. It honestly discloses this is a 'sample' of files rather than a complete listing, which is valuable behavioral context. However, it doesn't mention potential read safety implications, permission needs, or rate limits—though it's clearly a read operation given 'list' semantics and preview behavior.

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 tight sentences plus a compact docstring with Args. Efficient and front-loaded with the core purpose. The only minor waste is restating parameter info that also appears in the schema (limit default), but overall it's lean.

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 the has-output-schema flag is true (relieving the description of explaining return values) and only 2 params, the description is reasonably complete. The 'sample' disclosure for a listing tool is appropriate. But with no annotations and no explicit workflow guidance connecting it to siblings, there's room to add more about how it composes with get_archive or search_archives.

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 0%, so the description must compensate. It does explain 'id' as 'Archive id from search_archives' and 'limit' with default/max values, which adds meaning beyond the bare schema. However, it doesn't clarify what the limit units are or format expectations for id beyond the pointer to search_archives.

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?

Clear verb+resource purpose: 'List a sample of the files/objects in an archive's storage.' This distinguishes it from siblings like search_archives and get_archive by specifying it lists files within a single archive rather than searching across archives.

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 says id comes from search_archives, providing a useful prerequisite for sourcing the id. However, it doesn't explicitly state when to use this vs get_archive or get_schema_card, or any exclusions. The context implies it complements get_archive (which likely returns archive metadata) but doesn't say so.

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