oncofiles

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior: scanning for specific issues and, based on the 'dry_run' parameter, either reporting issues or making changes (moving files, renaming folders, cleaning up backups). It clarifies the default behavior (dry_run=True) and the impact of setting it to False, which is crucial for a mutation tool. However, it does not mention potential side effects, permissions required, or rate limits.

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 appropriately sized and front-loaded, starting with a clear purpose statement followed by specific scanning targets and parameter details. Every sentence earns its place by providing essential information without redundancy. The structure is logical, with a brief overview and then focused details on arguments.

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 tool's complexity (a mutation tool with behavioral dependencies on a parameter) and the presence of an output schema (which likely covers return values), the description is mostly complete. It covers purpose, usage context, parameter semantics, and behavioral traits. However, without annotations, it could benefit from mentioning permissions or potential risks, but the output schema reduces the need to explain return values, making it adequate for most contexts.

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 input schema has 0% description coverage and only one parameter ('dry_run') with no schema description. The description compensates fully by explaining the parameter's semantics: it defines what 'dry_run' does (report issues without changes if True, make changes if False), specifies the default value (True), and details the actions taken when False (move files, rename folders, clean up backups). This adds significant meaning beyond the bare schema.

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 clearly states the tool's purpose with specific verbs ('detect and fix') and resources ('GDrive folder structure issues'), and it enumerates the exact types of issues scanned (unknown folders, root-level files, empty managed folders, stale backup folders). This distinguishes it from sibling tools like 'gdrive_fix_permissions' or 'gdrive_sync', which address different aspects of GDrive management.

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 provides clear context for when to use this tool—specifically for addressing folder structure issues in GDrive. However, it does not explicitly state when not to use it or name alternatives among sibling tools (e.g., 'gdrive_fix_permissions' for permission issues or 'gdrive_sync' for synchronization). The guidance is implied but lacks explicit exclusions or comparisons.

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