env_sweep

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

Annotations already declare destructiveHint=true, readOnlyHint=false and openWorldHint=false, so the description's job is to add detail, and it does say what is affected: expired/dead leases are stopped and squatters are reclaimed. The gap is the undefined 'strict' mode — the description implies two behavioral regimes without saying how either is selected, which matters for a destructive tool.

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?

A single tight sentence with the primary action front-loaded and the subordinate behaviors after the colon. It is dense with unexplained terms, but there is no padding or repetition.

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 zero-parameter, no-output-schema, destructive tool the description covers the main outcome, but it leaves two things unresolved: what a 'squatter' is and how 'strict' mode is triggered when no input exists. An agent can call it, but cannot predict which of the two described behaviors will occur.

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?

With zero parameters and 100% schema coverage there is nothing for the schema to document, so the baseline is high. The mention of a 'strict' mode is the only wrinkle, since it hints at a switch that no parameter can set, but no parameter is misdocumented.

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?

It names a specific action (reconcile leases) and enumerates sub-actions (stop expired/dead, report or reclaim squatters), which is more than a restatement of the name. However, the core nouns are jargon ('leases', 'squatters') and it never distinguishes itself from env_up/env_down/env_ls, so an agent must infer that this is the cleanup/reaper tool.

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 statement of when to reach for env_sweep versus env_down or env_ls, and no prerequisites or safety conditions. The only routing hint is the unexplained 'under strict' clause, which is not actionable guidance.

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