onelake_rm

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, yet it only states the delete action. It does not disclose that deletion is likely permanent and irreversible, that removing a non-empty directory requires recursive=true, or what happens when the path does not exist. For a destructive tool, these are material gaps.

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 a single front-loaded sentence with no wasted words, which is efficient. However, it is under-specified rather than genuinely concise: one sentence is insufficient for a destructive tool with four parameters and zero annotation support.

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 destructive tool with no annotations, no output schema, and 0% schema description coverage, this description is far from complete. It omits recursive semantics, permanence, path formats, and workspace/lakehouse resolution behavior. An agent cannot safely invoke this tool based on this description alone.

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 for the four undocumented parameters, but it adds almost nothing. It does not explain path formats, how lakehouse/workspace resolve, or what the recursive flag does — arguably the most safety-critical parameter since deleting a directory without it will behave differently (or fail).

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 specific verb (Delete) and a specific resource (file or directory from OneLake), making the core operation unambiguous. It distinguishes at the operation level from the onelake_ls/read/write siblings, but does not explicitly differentiate from the closely related onelake_delete_shortcut, which is a similar destructive action on a different resource type.

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?

No guidance is provided on when to use this tool versus alternatives such as onelake_delete_shortcut (shortcuts) or vacuum_delta (delta table cleanup). It also does not mention prerequisites like set_lakehouse/set_workspace or any conditions for when not to use the tool.

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