kernel_files

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

No annotations are provided, so the description must carry the behavioral disclosure burden. The parenthetical 'metadata' hints that this tool does not return file contents, but it does not mention pagination behavior, required ref relationship, output shape, or any side effects. This leaves significant behavioral information undisclosed.

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 short and front-loads the primary verb, so it is not verbose. However, it is under-specified to the point of being a phrase rather than a useful definition. It is concise but not appropriately complete for a tool with undocumented parameters and no 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?

Given no output schema, no annotations, and zero parameter documentation, the description leaves too much implicit. An agent cannot confidently determine what ref means, what metadata fields will be returned, or how this tool relates to kernel_output. The description is too incomplete for correct invocation.

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%: both 'ref' and 'page_size' have empty descriptions. The tool description adds no meaning to either parameter, failing to explain what ref refers to or how page_size affects results. The description does not compensate for the schema gap at all.

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 states a clear verb and resource: 'List kernel output files (metadata)'. It explicitly scopes the operation to listing metadata rather than downloading content. However, it does not differentiate itself from closely related siblings such as kernel_output or list_model_version_files.

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?

There is no guidance about when to use this tool versus alternatives like kernel_output or kernel_logs. The description implies a listing use case, but it does not state exclusions, prerequisites, or which sibling would be more appropriate for retrieving file contents.

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